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) ;
43 
44  /// Return internal file descriptor, if any
45  virtual int fileno(void) ;
46 
47  /// Gets information about a file descriptor.
48  /// @note Not all plug-ins will fill all the fields, but st_size is
49  /// a reasonable expectation.
50  /// @note Default implementation combining seek/tell is provided.
51  virtual struct ::stat fstat(void) ;
52 
53  /// Read.
54  /// @param buffer Where to store the data.
55  /// @param count Number of bytes to read.
56  /// @return Number of bytes actually read.
57  virtual size_t read(char* buffer, size_t count) ;
58 
59  /// Write.
60  /// @param buffer Data to write.
61  /// @param count Number of bytes to write.
62  /// @return Number of bytes actually written.
63  virtual size_t write(const char* buffer, size_t count) ;
64 
65  /// Read into multiple buffers.
66  /// @param vector An array with 'count' iovec structs.
67  /// @param count Number of elements in vector.
68  /// @return The total size read.
69  /// @note See man readv.
70  /// @note A default implementation using read is provided.
71  virtual size_t readv(const struct iovec* vector, size_t count) ;
72 
73  /// Write from multiple buffers.
74  /// @param vector An array with 'count' iovec structs.
75  /// @param count Number of elements in vector.
76  /// @return The total size written.
77  /// @note See man writev.
78  /// @note A default implementation using write is provided.
79  virtual size_t writev(const struct iovec* vector, size_t count) ;
80 
81  /// Read from the given offset without changing the file offset.
82  /// @param buffer Where to put the data.
83  /// @param count Number of bytes to read.
84  /// @param offset The operation offset.
85  /// @note A default implementation using read/seek/tell is provided.
86  virtual size_t pread(void* buffer, size_t count, off_t offset) ;
87 
88  /// Write from the given offset without changing the file offset.
89  /// @param buffer Data to write.
90  /// @param count Number of bytes to read.
91  /// @param offset The operation offset.
92  /// @note A default implementation using read/seek/tell is provided.
93  virtual size_t pwrite(const void* buffer, size_t count, off_t offset) ;
94 
95  /// Move the cursor.
96  /// @param offset The offset.
97  /// @param whence Reference.
98  virtual void seek(off_t offset, Whence whence) ;
99 
100  /// Return the cursor position.
101  virtual off_t tell(void) ;
102 
103  /// Flush the buffer.
104  virtual void flush(void) ;
105 
106  /// Return true if end of file.
107  virtual bool eof(void) ;
108  };
109 
110  /// IO Driver
111  class IODriver: public virtual BaseInterface, public virtual BaseFactory {
112  public:
113  /// Use this flag in addition to the standard ones to skip any
114  /// security check (i.e. token validation)
115  /// Example: createIOHandler("/file.txt", O_RDONLY | IODriver::kInsecure, extras);
116  enum { kInsecure = 010 };
117 
118  /// Virtual destructor
119  virtual ~IODriver();
120 
121  /// String ID of the implementation.
122  virtual std::string getImplId(void) const throw() = 0;
123 
124  /// Instantiate a implementation of IOHandler
125  /// @param pfn The file name.
126  /// @param flags The open mode. See man 2 open.
127  /// @param extras As was given by the PoolHandler.
128  /// @param mode When called with O_CREAT, it will be used to create the file.
129  virtual IOHandler* createIOHandler(const std::string& pfn,
130  int flags,
131  const Extensible& extras,
132  mode_t mode = 0660) ;
133  static IOHandler* createIOHandler(IODriver* factory,
134  const std::string& pfn,
135  int flags,
136  const Extensible& extras,
137  mode_t mode = 0660) ;
138 
139  /// Must be called when the front-end is done writing.
140  /// @param pfn The file name.
141  /// @param loc The Location object as returned by whereToWrite
142  virtual void doneWriting(const Location& loc) ;
143 
144  protected:
145  friend class StackInstance;
146 
147  virtual void setSecurityContext(const SecurityContext* ctx) ;
148  static void setSecurityContext(IODriver* i,
149  const SecurityContext* ctx) ;
150  };
151 
152  /// Plug-ins must implement a concrete factory to be instantiated.
153  class IODriverFactory: public virtual BaseFactory {
154  public:
155  /// Virtual destructor
156  virtual ~IODriverFactory();
157 
158  protected:
159  friend class StackInstance;
160 
161  /// Create a IODriver
162  virtual IODriver* createIODriver(PluginManager* pm) ;
163  static IODriver* createIODriver(IODriverFactory* factory, PluginManager* pm) ;
164  };
165 
166 };
167 
168 #endif // DMLITE_CPP_IO_H
Security context. To be created by the Authn.
Definition: authn.h:73
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
Represent the complete location of a file.
Definition: pooldriver.h:50
virtual size_t write(const char *buffer, size_t count)
Definition: dmlite.h:161
virtual void seek(off_t offset, Whence whence)
virtual ~IOHandler()
Virtual destructor.
Current position.
Definition: io.h:29
virtual size_t read(char *buffer, size_t count)
Definition: io.h:116
virtual void doneWriting(const Location &loc)
CatalogInterface can only be instantiated through this class.
Definition: dmlite.h:42
virtual bool eof(void)
Return true if end of file.
virtual ~IODriver()
Virtual destructor.
std::string getImplId(void) const
String ID of the implementation.
Definition: io.h:37
virtual int fileno(void)
Return internal file descriptor, if any.
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:153
virtual size_t readv(const struct iovec *vector, size_t count)
Base class for factories.
Definition: base.h:48
Extensible types (hold metadata).
virtual void setSecurityContext(const SecurityContext *ctx)
Set the security context.
virtual std::string getImplId(void) const =0
String ID of the implementation.
Helpful typedef for KeyValue containers.
Definition: extensible.h:20
virtual IOHandler * createIOHandler(const std::string &pfn, int flags, const Extensible &extras, mode_t mode=0660)
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:111
virtual void close(void)
Close.
virtual struct::stat fstat(void)