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