dmlite  0.6
io.h
Go to the documentation of this file.
1 /// @file include/dmlite/cpp/io.h
2 /// @brief I/O API. Abstracts how to write or read to/from a disk within
3 /// a pool.
4 /// @author Alejandro Álvarez Ayllón <aalvarez@cern.ch>
5 #ifndef DMLITE_CPP_IO_H
6 #define DMLITE_CPP_IO_H
7 
8 #include "dmlite/common/config.h"
9 #include "base.h"
10 #include "exceptions.h"
11 #include "utils/extensible.h"
12 
13 #include <fcntl.h>
14 #include <map>
15 #include <sys/stat.h>
16 #include <sys/uio.h>
17 
18 namespace dmlite {
19 
20  // Forward declarations.
21  class Location;
22  class PluginManager;
23  class StackInstance;
24 
25  /// IO interface
26  class IOHandler {
27  public:
28  enum Whence { kSet = SEEK_SET, ///< Beginning of the file
29  kCur = SEEK_CUR, ///< Current position
30  kEnd = SEEK_END ///< End of file
31  };
32 
33  /// Virtual destructor
34  virtual ~IOHandler();
35 
36  /// String ID of the implementation.
37  std::string getImplId(void) const throw() {
38  return std::string("IOHandler");
39  }
40 
41  /// Close
42  virtual void close(void) throw (DmException);
43 
44  /// Gets information about a file descriptor.
45  /// @note Not all plug-ins will fill all the fields, but st_size is
46  /// a reasonable expectation.
47  /// @note Default implementation combining seek/tell is provided.
48  virtual struct ::stat fstat(void) throw (DmException);
49 
50  /// Read.
51  /// @param buffer Where to store the data.
52  /// @param count Number of bytes to read.
53  /// @return Number of bytes actually read.
54  virtual size_t read(char* buffer, size_t count) throw (DmException);
55 
56  /// Write.
57  /// @param buffer Data to write.
58  /// @param count Number of bytes to write.
59  /// @return Number of bytes actually written.
60  virtual size_t write(const char* buffer, size_t count) throw (DmException);
61 
62  /// Read into multiple buffers.
63  /// @param vector An array with 'count' iovec structs.
64  /// @param count Number of elements in vector.
65  /// @return The total size read.
66  /// @note See man readv.
67  /// @note A default implementation using read is provided.
68  virtual size_t readv(const struct iovec* vector, size_t count) throw (DmException);
69 
70  /// Write from multiple buffers.
71  /// @param vector An array with 'count' iovec structs.
72  /// @param count Number of elements in vector.
73  /// @return The total size written.
74  /// @note See man writev.
75  /// @note A default implementation using write is provided.
76  virtual size_t writev(const struct iovec* vector, size_t count) throw (DmException);
77 
78  /// Read from the given offset without changing the file offset.
79  /// @param buffer Where to put the data.
80  /// @param count Number of bytes to read.
81  /// @param offset The operation offset.
82  /// @note A default implementation using read/seek/tell is provided.
83  virtual size_t pread(void* buffer, size_t count, off_t offset) throw (DmException);
84 
85  /// Write from the given offset without changing the file offset.
86  /// @param buffer Data to write.
87  /// @param count Number of bytes to read.
88  /// @param offset The operation offset.
89  /// @note A default implementation using read/seek/tell is provided.
90  virtual size_t pwrite(const void* buffer, size_t count, off_t offset) throw (DmException);
91 
92  /// Move the cursor.
93  /// @param offset The offset.
94  /// @param whence Reference.
95  virtual void seek(off_t offset, Whence whence) throw (DmException);
96 
97  /// Return the cursor position.
98  virtual off_t tell(void) throw (DmException);
99 
100  /// Flush the buffer.
101  virtual void flush(void) throw (DmException);
102 
103  /// Return true if end of file.
104  virtual bool eof(void) throw (DmException);
105  };
106 
107  /// IO Driver
108  class IODriver: public virtual BaseInterface, public virtual BaseFactory {
109  public:
110  /// Use this flag in addition to the standard ones to skip any
111  /// security check (i.e. token validation)
112  /// Example: createIOHandler("/file.txt", O_RDONLY | IODriver::kInsecure, extras);
113  enum { kInsecure = 010 };
114 
115  /// Virtual destructor
116  virtual ~IODriver();
117 
118  /// String ID of the implementation.
119  virtual std::string getImplId(void) const throw() = 0;
120 
121  /// Instantiate a implementation of IOHandler
122  /// @param pfn The file name.
123  /// @param flags The open mode. See man 2 open.
124  /// @param extras As was given by the PoolHandler.
125  /// @param mode When called with O_CREAT, it will be used to create the file.
126  virtual IOHandler* createIOHandler(const std::string& pfn,
127  int flags,
128  const Extensible& extras,
129  mode_t mode = 0660) throw (DmException);
130  static IOHandler* createIOHandler(IODriver* factory,
131  const std::string& pfn,
132  int flags,
133  const Extensible& extras,
134  mode_t mode = 0660) throw (DmException);
135 
136  /// Must be called when the front-end is done writing.
137  /// @param pfn The file name.
138  /// @param loc The Location object as returned by whereToWrite
139  virtual void doneWriting(const Location& loc) throw (DmException);
140 
141  protected:
142  friend class StackInstance;
143 
144  virtual void setSecurityContext(const SecurityContext* ctx) throw (DmException);
145  static void setSecurityContext(IODriver* i,
146  const SecurityContext* ctx) throw (DmException);
147  };
148 
149  /// Plug-ins must implement a concrete factory to be instantiated.
150  class IODriverFactory: public virtual BaseFactory {
151  public:
152  /// Virtual destructor
153  virtual ~IODriverFactory();
154 
155  protected:
156  friend class StackInstance;
157 
158  /// Create a IODriver
159  virtual IODriver* createIODriver(PluginManager* pm) throw (DmException);
160  static IODriver* createIODriver(IODriverFactory* factory, PluginManager* pm) throw (DmException);
161  };
162 
163 };
164 
165 #endif // DMLITE_CPP_IO_H
virtual size_t pwrite(const void *buffer, size_t count, off_t offset)
virtual size_t writev(const struct iovec *vector, size_t count)
Beginning of the file.
Definition: io.h:28
Base class for interfaces.
Definition: base.h:18
virtual size_t write(const char *buffer, size_t count)
Definition: dmlite.h:161
virtual void seek(off_t offset, Whence whence)
Security context. To be created by the Authn.
Definition: authn.h:64
virtual ~IOHandler()
Virtual destructor.
Header generated by CMake with the build configuration used.
Current position.
Definition: io.h:29
Represent the complete location of a file.
Definition: pooldriver.h:42
Base exception class.
Definition: exceptions.h:17
virtual size_t read(char *buffer, size_t count)
CatalogInterface can only be instantiated through this class.
Definition: dmlite.h:42
virtual bool eof(void)
Return true if end of file.
std::string getImplId(void) const
String ID of the implementation.
Definition: io.h:37
IO interface.
Definition: io.h:26
Whence
Definition: io.h:28
Exceptions used by the API.
Plug-ins must implement a concrete factory to be instantiated.
Definition: io.h:150
Helpful typedef for KeyValue containers.
Definition: extensible.h:20
virtual size_t readv(const struct iovec *vector, size_t count)
Base class for factories.
Definition: base.h:48
Extensible types (hold metadata).
Base interfaces.
virtual off_t tell(void)
Return the cursor position.
virtual void flush(void)
Flush the buffer.
virtual size_t pread(void *buffer, size_t count, off_t offset)
End of file.
Definition: io.h:30
IO Driver.
Definition: io.h:108
Namespace for the dmlite C++ API.
Definition: authn.h:15
virtual void close(void)
Close.
virtual struct::stat fstat(void)