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