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

Generated on 11 Jul 2013 for dmlite by  doxygen 1.4.7