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 "../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 
16 namespace dmlite {
17 
18  // Forward declarations.
19  class Location;
20  class PluginManager;
21  class StackInstance;
22 
23  /// IO interface
24  class IOHandler {
25  public:
26  enum Whence { kSet = SEEK_SET, ///< Beginning of the file
27  kCur = SEEK_CUR, ///< Current position
28  kEnd = SEEK_END ///< End of file
29  };
30 
31  /// Virtual destructor
32  virtual ~IOHandler();
33 
34  /// Close
35  virtual void close(void) throw (DmException);
36 
37  /// Gets information about a file descriptor.
38  /// @note Not all plug-ins will fill all the fields, but st_size is
39  /// a reasonable expectation.
40  /// @note Default implementation combining seek/tell is provided.
41  virtual struct stat fstat(void) throw (DmException);
42 
43  /// Read.
44  /// @param buffer Where to store the data.
45  /// @param count Number of bytes to read.
46  /// @return Number of bytes actually read.
47  virtual size_t read(char* buffer, size_t count) throw (DmException);
48 
49  /// Write.
50  /// @param buffer Data to write.
51  /// @param count Number of bytes to write.
52  /// @return Number of bytes actually written.
53  virtual size_t write(const char* buffer, size_t count) throw (DmException);
54 
55  /// Read into multiple buffers.
56  /// @param vector An array with 'count' iovec structs.
57  /// @param count Number of elements in vector.
58  /// @return The total size read.
59  /// @note See man readv.
60  /// @note A default implementation using read is provided.
61  virtual size_t readv(const struct iovec* vector, size_t count) throw (DmException);
62 
63  /// Write from multiple buffers.
64  /// @param vector An array with 'count' iovec structs.
65  /// @param count Number of elements in vector.
66  /// @return The total size written.
67  /// @note See man writev.
68  /// @note A default implementation using write is provided.
69  virtual size_t writev(const struct iovec* vector, size_t count) throw (DmException);
70 
71  /// Read from the given offset without changing the file offset.
72  /// @param buffer Where to put the data.
73  /// @param count Number of bytes to read.
74  /// @param offset The operation offset.
75  /// @note A default implementation using read/seek/tell is provided.
76  virtual size_t pread(void* buffer, size_t count, off_t offset) throw (DmException);
77 
78  /// Write from the given offset without changing the file offset.
79  /// @param buffer Data to write.
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 pwrite(const void* buffer, size_t count, off_t offset) throw (DmException);
84 
85  /// Move the cursor.
86  /// @param offset The offset.
87  /// @param whence Reference.
88  virtual void seek(off_t offset, Whence whence) throw (DmException);
89 
90  /// Return the cursor position.
91  virtual off_t tell(void) throw (DmException);
92 
93  /// Flush the buffer.
94  virtual void flush(void) throw (DmException);
95 
96  /// Return true if end of file.
97  virtual bool eof(void) throw (DmException);
98  };
99 
100  /// IO Driver
101  class IODriver {
102  public:
103  /// Use this flag in addition to the standard ones to skip any
104  /// security check (i.e. token validation)
105  /// Example: createIOHandler("/file.txt", O_RDONLY | IODriver::kInsecure, extras);
106  enum { kInsecure = 010 };
107 
108  /// Virtual destructor
109  virtual ~IODriver();
110 
111  /// String ID of the implementation.
112  virtual std::string getImplId(void) const throw() = 0;
113 
114  /// Instantiate a implementation of IOHandler
115  /// @param pfn The file name.
116  /// @param flags The open mode. See man 2 open.
117  /// @param extras As was given by the PoolHandler.
118  /// @param mode When called with O_CREAT, it will be used to create the file.
119  virtual IOHandler* createIOHandler(const std::string& pfn,
120  int flags,
121  const Extensible& extras,
122  mode_t mode = 0660) throw (DmException);
123 
124  /// Must be called when the front-end is done writing.
125  /// @param pfn The file name.
126  /// @param loc The Location object as returned by whereToWrite
127  virtual void doneWriting(const Location& loc) throw (DmException);
128 
129  protected:
130  friend class StackInstance;
131 
132  virtual void setSecurityContext(const SecurityContext* ctx) throw (DmException);
133  static void setSecurityContext(IODriver* i,
134  const SecurityContext* ctx) throw (DmException);
135  };
136 
137  /// Plug-ins must implement a concrete factory to be instantiated.
138  class IOFactory: public virtual BaseFactory {
139  public:
140  /// Virtual destructor
141  virtual ~IOFactory();
142 
143  protected:
144  friend class StackInstance;
145 
146  /// Create a IODriver
147  virtual IODriver* createIODriver(PluginManager* pm) throw (DmException);
148  };
149 
150 };
151 
152 #endif // DMLITE_CPP_IO_H