include/dmlite/cpp/io.h

Go to the documentation of this file.
00001 /// @file   include/dmlite/cpp/io.h
00002 /// @brief  I/O API. Abstracts how to write or read to/from a disk within
00003 ///         a pool.
00004 /// @author Alejandro Álvarez Ayllón <aalvarez@cern.ch>
00005 #ifndef DMLITE_CPP_IO_H
00006 #define DMLITE_CPP_IO_H
00007 
00008 #include "dmlite/common/config.h"
00009 #include "base.h"
00010 #include "exceptions.h"
00011 #include "utils/extensible.h"
00012 
00013 #include <fcntl.h>
00014 #include <map>
00015 #include <sys/stat.h>
00016 #include <sys/uio.h>
00017 
00018 namespace dmlite {
00019   
00020   // Forward declarations.
00021   class Location;
00022   class PluginManager;
00023   class StackInstance;
00024   
00025   /// IO interface
00026   class IOHandler {
00027    public:
00028     enum Whence { kSet = SEEK_SET, ///< Beginning of the file
00029                   kCur = SEEK_CUR, ///< Current position
00030                   kEnd = SEEK_END  ///< End of file
00031                 };
00032      
00033     /// Virtual destructor
00034     virtual ~IOHandler();
00035 
00036     /// String ID of the implementation.
00037     std::string getImplId(void) const throw() {
00038       return std::string("IOHandler");
00039     }
00040 
00041     /// Close
00042     virtual void close(void) throw (DmException);
00043 
00044     /// Gets information about a file descriptor.
00045     /// @note Not all plug-ins will fill all the fields, but st_size is
00046     ///       a reasonable expectation.
00047     /// @note Default implementation combining seek/tell is provided.
00048     virtual struct ::stat fstat(void) throw (DmException);
00049 
00050     /// Read.
00051     /// @param buffer Where to store the data.
00052     /// @param count  Number of bytes to read.
00053     /// @return       Number of bytes actually read.
00054     virtual size_t read(char* buffer, size_t count) throw (DmException);
00055 
00056     /// Write.
00057     /// @param buffer Data to write.
00058     /// @param count  Number of bytes to write.
00059     /// @return       Number of bytes actually written.
00060     virtual size_t write(const char* buffer, size_t count) throw (DmException);
00061 
00062     /// Read into multiple buffers.
00063     /// @param vector An array with 'count' iovec structs.
00064     /// @param count  Number of elements in vector.
00065     /// @return       The total size read.
00066     /// @note         See man readv.
00067     /// @note         A default implementation using read is provided.
00068     virtual size_t readv(const struct iovec* vector, size_t count) throw (DmException);
00069 
00070     /// Write from multiple buffers.
00071     /// @param vector An array with 'count' iovec structs.
00072     /// @param count  Number of elements in vector.
00073     /// @return       The total size written.
00074     /// @note         See man writev.
00075     /// @note         A default implementation using write is provided.
00076     virtual size_t writev(const struct iovec* vector, size_t count) throw (DmException);
00077 
00078     /// Read from the given offset without changing the file offset.
00079     /// @param buffer Where to put the data.
00080     /// @param count  Number of bytes to read.
00081     /// @param offset The operation offset.
00082     /// @note         A default implementation using read/seek/tell is provided.
00083     virtual size_t pread(void* buffer, size_t count, off_t offset) throw (DmException);
00084 
00085     /// Write from the given offset without changing the file offset.
00086     /// @param buffer Data to write.
00087     /// @param count  Number of bytes to read.
00088     /// @param offset The operation offset.
00089     /// @note         A default implementation using read/seek/tell is provided.
00090     virtual size_t pwrite(const void* buffer, size_t count, off_t offset) throw (DmException);
00091 
00092     /// Move the cursor.
00093     /// @param offset The offset.
00094     /// @param whence Reference.
00095     virtual void seek(off_t offset, Whence whence) throw (DmException);
00096 
00097     /// Return the cursor position.
00098     virtual off_t tell(void) throw (DmException);
00099 
00100     /// Flush the buffer.
00101     virtual void flush(void) throw (DmException);
00102 
00103     /// Return true if end of file.
00104     virtual bool eof(void) throw (DmException);
00105   };
00106 
00107   /// IO Driver
00108   class IODriver: public virtual BaseInterface, public virtual BaseFactory {
00109    public:
00110     /// Use this flag in addition to the standard ones to skip any
00111     /// security check (i.e. token validation)
00112     /// Example: createIOHandler("/file.txt", O_RDONLY | IODriver::kInsecure, extras);
00113     enum { kInsecure = 010 };
00114 
00115     /// Virtual destructor
00116     virtual ~IODriver();
00117 
00118     /// String ID of the implementation.
00119     virtual std::string getImplId(void) const throw() = 0;
00120 
00121     /// Instantiate a implementation of IOHandler
00122     /// @param pfn    The file name.
00123     /// @param flags  The open mode. See man 2 open.
00124     /// @param extras As was given by the PoolHandler.
00125     /// @param mode   When called with O_CREAT, it will be used to create the file.
00126     virtual IOHandler* createIOHandler(const std::string& pfn,
00127                                        int flags,
00128                                        const Extensible& extras,
00129                                        mode_t mode = 0660) throw (DmException);
00130     static IOHandler* createIOHandler(IODriver* factory,
00131                                       const std::string& pfn,
00132                                       int flags,
00133                                       const Extensible& extras,
00134                                       mode_t mode = 0660) throw (DmException);
00135     
00136     /// Must be called when the front-end is done writing.
00137     /// @param pfn The file name.
00138     /// @param loc The Location object as returned by whereToWrite
00139     virtual void doneWriting(const Location& loc) throw (DmException);
00140 
00141    protected:
00142     friend class StackInstance;
00143 
00144     virtual void setSecurityContext(const SecurityContext* ctx) throw (DmException);
00145     static void  setSecurityContext(IODriver* i,
00146                                     const SecurityContext* ctx) throw (DmException);
00147   };
00148 
00149   /// Plug-ins must implement a concrete factory to be instantiated.
00150   class IODriverFactory: public virtual BaseFactory {
00151    public:
00152     /// Virtual destructor
00153     virtual ~IODriverFactory();
00154 
00155    protected:
00156     friend class StackInstance;
00157 
00158     /// Create a IODriver
00159     virtual IODriver* createIODriver(PluginManager* pm) throw (DmException);
00160     static IODriver* createIODriver(IODriverFactory* factory, PluginManager* pm) throw (DmException);
00161   };
00162 
00163 };
00164 
00165 #endif // DMLITE_CPP_IO_H

Generated on 18 Nov 2014 for dmlite by  doxygen 1.4.7