FilebufIO.h

Go to the documentation of this file.
00001 //# FilebufIO.h: Class for buffered IO on a file
00002 //# Copyright (C) 1996,1997,1999,2001,2002
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef CASA_FILEBUFIO_H
00029 #define CASA_FILEBUFIO_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/casa/IO/ByteIO.h>
00035 #include <casacore/casa/BasicSL/String.h>
00036 
00037 
00038 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00039 
00040 // <summary> Class for buffered IO on a file.</summary>
00041 
00042 // <use visibility=export>
00043 
00044 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tByteIO" demos="">
00045 // </reviewed>
00046 
00047 // <prerequisite> 
00048 //  <li> <linkto class=ByteIO>ByteIO</linkto>
00049 // </prerequisite>
00050 
00051 // <synopsis>
00052 // This class is a specialization of class
00053 // <linkto class=ByteIO>ByteIO</linkto>.
00054 // This class is doing IO on a file in a buffered way to reduce the number
00055 // of file accesses as much as possible.
00056 // It is part of the entire IO framework. It can for
00057 // instance be used to store data in canonical format in a file
00058 // in an IO-efficient way
00059 // <br>
00060 // The buffer size is dynamic, so any time it can be set as needed.
00061 // <p>
00062 // It is also possible to construct a <src>FilebufIO</src> object
00063 // from a file descriptor (e.g. for a pipe or socket).
00064 // The constructor will determine automatically if the file is
00065 // readable, writable and seekable.
00066 // </synopsis>
00067 
00068 // <example>
00069 // This example shows how FilebufIO can be used with an fd.
00070 // It uses the fd for a regular file, which could be done in an easier
00071 // way using class <linkto class=RegularFileIO>RegularFileIO</linkto>.
00072 // However, when using pipes or sockets, this would be the only way.
00073 // <srcblock>
00074 //    // Get a file descriptor for the file.
00075 //    int fd = open ("file.name");
00076 //    // Use that as the source of AipsIO (which will also use CanonicalIO).
00077 //    FilebufIO fio (fd);
00078 //    AipsIO stream (&fio);
00079 //    // Read the data.
00080 //    Int vali;
00081 //    Bool valb;
00082 //    stream >> vali >> valb;
00083 // </srcblock>
00084 // </example>
00085 
00086 // <motivation> 
00087 // The stdio package was used, but it proved to be very slow on SOlaris.
00088 // After a seek the buffer was refreshed, which increased the number
00089 // of file accesses enormously.
00090 // Also the interaction between reads and writes in stdio was poor.
00091 // </motivation>
00092 
00093 
00094 class FilebufIO: public ByteIO
00095 {
00096 public: 
00097     // Default constructor.
00098     // A stream can be attached using the attach function.
00099     FilebufIO();
00100 
00101     // Construct from the given file descriptor.
00102     // Note that the destructor and the detach function implicitly close
00103     // the file descriptor.
00104     explicit FilebufIO (int fd, uInt bufferSize=16384);
00105 
00106     // Attach to the given file descriptor.
00107     // Note that the destructor and the detach function implicitly close
00108     // the file descriptor.
00109     void attach (int fd, uInt bufferSize=16384);
00110 
00111     // The destructor closes the file when it was owned and opened and not
00112     // closed yet.
00113     virtual ~FilebufIO();
00114     
00115     // Write the number of bytes.
00116     virtual void write (Int64 size, const void* buf);
00117 
00118     // Read <src>size</src> bytes from the File. Returns the number of bytes
00119     // actually read. Will throw an exception (AipsError) if the requested
00120     // number of bytes could not be read unless throwException is set to
00121     // False. Will always throw an exception if the file is not readable or
00122     // the system call returns an undocumented value.
00123     virtual Int64 read (Int64 size, void* buf, Bool throwException=True);    
00124 
00125     // Flush the current buffer.
00126     virtual void flush();
00127 
00128     // Resync the file (i.e. empty the current buffer).
00129     virtual void resync();
00130   
00131     // Get the length of the byte stream.
00132     virtual Int64 length();
00133        
00134     // Is the IO stream readable?
00135     virtual Bool isReadable() const;
00136 
00137     // Is the IO stream writable?
00138     virtual Bool isWritable() const;
00139 
00140     // Is the IO stream seekable?
00141     virtual Bool isSeekable() const;
00142 
00143     // Get the file name of the file attached.
00144     virtual String fileName() const;
00145 
00146     // Get the buffer size.
00147     uInt bufferSize() const
00148       { return itsBufSize; }
00149 
00150 protected:
00151     // Detach the FILE. Close it when needed.
00152     void detach (Bool closeFile=False);
00153 
00154     // Determine if the file descriptor is readable and/or writable.
00155     void fillRWFlags (int fd);
00156 
00157     // Determine if the file is seekable.
00158     void fillSeekable();
00159 
00160     // Reset the position pointer to the given value. It returns the
00161     // new position.
00162     virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption);
00163 
00164     // Set a new buffer size.
00165     // If a buffer was already existing, flush and delete it.
00166     void setBuffer (Int64 bufSize);
00167 
00168     // Write a buffer of given length into the file at given offset.
00169     void writeBuffer (Int64 offset, const char* buf, Int64 size);
00170 
00171     // Read a buffer of given length from the file at given offset.
00172     Int64 readBuffer (Int64 offset, char* buf, Int64 size,
00173                      Bool throwException);
00174 
00175     // Write a block into the stream at the current offset.
00176     // It is guaranteed that the block fits in a single buffer.
00177     void writeBlock (Int64 size, const char* buf);
00178 
00179     // Read a block from the stream at the current offset.
00180     // It is guaranteed that the block fits in a single buffer.
00181     Int64 readBlock (Int64 size, char* buf, Bool throwException);
00182 
00183 private:
00184     Bool        itsSeekable;
00185     Bool        itsReadable;
00186     Bool        itsWritable;
00187     int         itsFile;
00188     Int64       itsBufSize;          // the buffer size
00189     Int64       itsBufLen;           // the current buffer length used
00190     char*       itsBuffer;
00191     Int64       itsBufOffset;        // file offset of current buffer
00192     Int64       itsOffset;           // current file offset
00193     Int64       itsSeekOffset;       // offset last seeked
00194     Bool        itsDirty;            // data written into current buffer?
00195 
00196     // Copy constructor, should not be used.
00197     FilebufIO (const FilebufIO& that);
00198 
00199     // Assignment, should not be used.
00200     FilebufIO& operator= (const FilebufIO& that);
00201 };
00202 
00203 
00204 } //# NAMESPACE CASACORE - END
00205 
00206 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1