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     /// Return internal file descriptor, if any
00045     virtual int fileno(void) throw (DmException);
00046 
00047     /// Gets information about a file descriptor.
00048     /// @note Not all plug-ins will fill all the fields, but st_size is
00049     ///       a reasonable expectation.
00050     /// @note Default implementation combining seek/tell is provided.
00051     virtual struct ::stat fstat(void) throw (DmException);
00052 
00053     /// Read.
00054     /// @param buffer Where to store the data.
00055     /// @param count  Number of bytes to read.
00056     /// @return       Number of bytes actually read.
00057     virtual size_t read(char* buffer, size_t count) throw (DmException);
00058 
00059     /// Write.
00060     /// @param buffer Data to write.
00061     /// @param count  Number of bytes to write.
00062     /// @return       Number of bytes actually written.
00063     virtual size_t write(const char* buffer, size_t count) throw (DmException);
00064 
00065     /// Read into multiple buffers.
00066     /// @param vector An array with 'count' iovec structs.
00067     /// @param count  Number of elements in vector.
00068     /// @return       The total size read.
00069     /// @note         See man readv.
00070     /// @note         A default implementation using read is provided.
00071     virtual size_t readv(const struct iovec* vector, size_t count) throw (DmException);
00072 
00073     /// Write from multiple buffers.
00074     /// @param vector An array with 'count' iovec structs.
00075     /// @param count  Number of elements in vector.
00076     /// @return       The total size written.
00077     /// @note         See man writev.
00078     /// @note         A default implementation using write is provided.
00079     virtual size_t writev(const struct iovec* vector, size_t count) throw (DmException);
00080 
00081     /// Read from the given offset without changing the file offset.
00082     /// @param buffer Where to put the data.
00083     /// @param count  Number of bytes to read.
00084     /// @param offset The operation offset.
00085     /// @note         A default implementation using read/seek/tell is provided.
00086     virtual size_t pread(void* buffer, size_t count, off_t offset) throw (DmException);
00087 
00088     /// Write from the given offset without changing the file offset.
00089     /// @param buffer Data to write.
00090     /// @param count  Number of bytes to read.
00091     /// @param offset The operation offset.
00092     /// @note         A default implementation using read/seek/tell is provided.
00093     virtual size_t pwrite(const void* buffer, size_t count, off_t offset) throw (DmException);
00094 
00095     /// Move the cursor.
00096     /// @param offset The offset.
00097     /// @param whence Reference.
00098     virtual void seek(off_t offset, Whence whence) throw (DmException);
00099 
00100     /// Return the cursor position.
00101     virtual off_t tell(void) throw (DmException);
00102 
00103     /// Flush the buffer.
00104     virtual void flush(void) throw (DmException);
00105 
00106     /// Return true if end of file.
00107     virtual bool eof(void) throw (DmException);
00108   };
00109 
00110   /// IO Driver
00111   class IODriver: public virtual BaseInterface, public virtual BaseFactory {
00112    public:
00113     /// Use this flag in addition to the standard ones to skip any
00114     /// security check (i.e. token validation)
00115     /// Example: createIOHandler("/file.txt", O_RDONLY | IODriver::kInsecure, extras);
00116     enum { kInsecure = 010 };
00117 
00118     /// Virtual destructor
00119     virtual ~IODriver();
00120 
00121     /// String ID of the implementation.
00122     virtual std::string getImplId(void) const throw() = 0;
00123 
00124     /// Instantiate a implementation of IOHandler
00125     /// @param pfn    The file name.
00126     /// @param flags  The open mode. See man 2 open.
00127     /// @param extras As was given by the PoolHandler.
00128     /// @param mode   When called with O_CREAT, it will be used to create the file.
00129     virtual IOHandler* createIOHandler(const std::string& pfn,
00130                                        int flags,
00131                                        const Extensible& extras,
00132                                        mode_t mode = 0660) throw (DmException);
00133     static IOHandler* createIOHandler(IODriver* factory,
00134                                       const std::string& pfn,
00135                                       int flags,
00136                                       const Extensible& extras,
00137                                       mode_t mode = 0660) throw (DmException);
00138 
00139     /// Must be called when the front-end is done writing.
00140     /// @param pfn The file name.
00141     /// @param loc The Location object as returned by whereToWrite
00142     virtual void doneWriting(const Location& loc) throw (DmException);
00143 
00144    protected:
00145     friend class StackInstance;
00146 
00147     virtual void setSecurityContext(const SecurityContext* ctx) throw (DmException);
00148     static void  setSecurityContext(IODriver* i,
00149                                     const SecurityContext* ctx) throw (DmException);
00150   };
00151 
00152   /// Plug-ins must implement a concrete factory to be instantiated.
00153   class IODriverFactory: public virtual BaseFactory {
00154    public:
00155     /// Virtual destructor
00156     virtual ~IODriverFactory();
00157 
00158    protected:
00159     friend class StackInstance;
00160 
00161     /// Create a IODriver
00162     virtual IODriver* createIODriver(PluginManager* pm) throw (DmException);
00163     static IODriver* createIODriver(IODriverFactory* factory, PluginManager* pm) throw (DmException);
00164   };
00165 
00166 };
00167 
00168 #endif // DMLITE_CPP_IO_H

Generated on 4 May 2016 for dmlite by  doxygen 1.4.7