BucketFile.h

Go to the documentation of this file.
00001 //# BucketFile.h: File object for BucketCache
00002 //# Copyright (C) 1995,1996,1999,2001
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_BUCKETFILE_H
00029 #define CASA_BUCKETFILE_H
00030 
00031 //# Includes
00032 #include <casacore/casa/aips.h>
00033 #include <casacore/casa/IO/ByteIO.h>
00034 #include <casacore/casa/IO/MMapfdIO.h>
00035 #include <casacore/casa/IO/FilebufIO.h>
00036 #include <casacore/casa/BasicSL/String.h>
00037 #include <casacore/casa/Utilities/CountedPtr.h>
00038 #include <unistd.h>
00039 
00040 
00041 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00042 
00043 //# Forward Declarations
00044 class MultiFileBase;
00045 
00046 // <summary>
00047 // File object for BucketCache.
00048 // </summary>
00049 
00050 // <use visibility=local>
00051 
00052 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
00053 // </reviewed>
00054 
00055 //# <prerequisite>
00056 //# Classes you should understand before using this one.
00057 //# </prerequisite>
00058 
00059 // <etymology>
00060 // BucketFile represents a data file for the BucketCache class.
00061 // </etymology>
00062 
00063 // <synopsis>
00064 // A BucketFile object represents a data file. Currently it is used
00065 // by the Table system, but it can easily be turned into
00066 // a more general storage manager file class.
00067 // <br>
00068 // Creation of a BucketFile object does not open the file yet.
00069 // An explicit open call has to be given before the file can be used.
00070 // <p>
00071 // The file can be opened as an ordinary file (with a file descriptor)
00072 // or as a file in a MultiFileBase object. An ordinary file can be accessed
00073 // in 3 ways:
00074 // <ul>
00075 //  <li> In an unbuffered way, where the parent BucketCache class accesses
00076 //       a bucket at a time (and possibly keeps it in a cache).
00077 //  <li> In a memory-mapped way, where the parent BucketMapped class does
00078 //       the access using the MMapfdIO member.
00079 //  <li> In a buffered way, where the parent BucketBuffered class does
00080 //       the access using the FilebufIO member.
00081 // </ul>
00082 // A MultiFileBase file can only be accessed in the unbuffered way.
00083 // </synopsis> 
00084 
00085 // <motivation>
00086 // Encapsulate the file creation and access into a single class
00087 // to hide the file IO details.
00088 // </motivation>
00089 
00090 // <example>
00091 // <srcblock>
00092 //     // Create the file for the given storage manager.
00093 //     BucketFile file ("file.name");
00094 //     // Open the file and write into it.
00095 //     file.open();
00096 //     file.write (someBuffer, someLength);
00097 //     // Get the length of the file.
00098 //     uInt size = file.fileSize();
00099 // </srcblock>
00100 // </example>
00101 
00102 // <todo asof="$DATE:$">
00103 //  <li> Use the ByteIO classes when they are ready.
00104 // </todo>
00105 
00106 
00107 class BucketFile
00108 {
00109 public:
00110     // Create a BucketFile object for a new file.
00111     // The file with the given name will be created as a normal file or
00112     // as part of a MultiFileBase (if mfile != 0).
00113     // It can be indicated if a MMapfdIO and/or FilebufIO object must be
00114     // created for the file. If a MultiFileBase is used, memory-mapped IO
00115     // cannot be used and mappedFile is ignored.
00116     explicit BucketFile (const String& fileName,
00117                          uInt bufSizeFile=0, Bool mappedFile=False,
00118                          MultiFileBase* mfile=0);
00119 
00120     // Create a BucketFile object for an existing file.
00121     // The file should be opened by the <src>open</src>.
00122     // Tell if the file must be opened writable.
00123     // It can be indicated if a MMapfdIO and/or FilebufIO object must be
00124     // created for the file. If a MultiFileBase is used, memory-mapped IO
00125     // cannot be used and mappedFile is ignored.
00126     BucketFile (const String& fileName, Bool writable,
00127                 uInt bufSizeFile=0, Bool mappedFile=False,
00128                 MultiFileBase* mfile=0);
00129 
00130     // The destructor closes the file (if open).
00131     virtual ~BucketFile();
00132 
00133     // Make a (temporary) buffered IO object for this file.
00134     // That object should not close the file.
00135     virtual CountedPtr<ByteIO> makeFilebufIO (uInt bufferSize);
00136 
00137     // Get the mapped file object.
00138     MMapfdIO* mappedFile()
00139       { return mappedFile_p; }
00140 
00141     // Get the buffered file object.
00142     FilebufIO* bufferedFile()
00143       { return bufferedFile_p; }
00144 
00145     // Open the file if not open yet.
00146     virtual void open();
00147 
00148     // Close the file (if open).
00149     virtual void close();
00150 
00151     // Remove the file (and close it if needed).
00152     virtual void remove();
00153 
00154     // Fsync the file (i.e. force the data to be physically written).
00155     virtual void fsync();
00156 
00157     // Set the file to read/write access. It is reopened if not writable.
00158     // It does nothing if the file is already writable.
00159     virtual void setRW();
00160 
00161     // Get the file name.
00162     virtual const String& name() const;
00163     
00164     // Has the file logically been indicated as writable?
00165     Bool isWritable() const;
00166 
00167     // Read bytes from the file.
00168     virtual uInt read (void* buffer, uInt length);
00169 
00170     // Write bytes into the file.
00171     virtual uInt write (const void* buffer, uInt length);
00172 
00173     // Seek in the file.
00174     // <group>
00175     virtual void seek (Int64 offset);
00176     void seek (Int offset);
00177     // </group>
00178 
00179     // Get the (physical) size of the file.
00180     // This is doing a seek and sets the file pointer to end-of-file.
00181     virtual Int64 fileSize() const;
00182 
00183     // Is the file cached, mapped, or buffered?
00184     // <group>
00185     Bool isCached() const;
00186     Bool isMapped() const;
00187     Bool isBuffered() const;
00188     // </group>
00189 
00190 private:
00191     // The file name.
00192     String name_p;
00193     // The (logical) writability of the file.
00194     Bool isWritable_p;
00195     Bool isMapped_p;
00196     uInt bufSize_p;
00197     int  fd_p;    //  fd (if used) of unbuffered file
00198     // The unbuffered file.
00199     CountedPtr<ByteIO> file_p;
00200     // The optional mapped file.
00201     MMapfdIO* mappedFile_p;
00202     // The optional buffered file.
00203     FilebufIO* bufferedFile_p;
00204     // The possibly used MultiFileBase.
00205     MultiFileBase* mfile_p;
00206             
00207 
00208     // Forbid copy constructor.
00209     BucketFile (const BucketFile&);
00210 
00211     // Forbid assignment.
00212     BucketFile& operator= (const BucketFile&);
00213 
00214     // Create the mapped or buffered file object.
00215     void createMapBuf();
00216 
00217     // Delete the possible mapped or buffered file object.
00218     void deleteMapBuf();
00219 };
00220 
00221 
00222 inline const String& BucketFile::name() const
00223     { return name_p; }
00224 
00225 inline Bool BucketFile::isWritable() const
00226     { return isWritable_p; }
00227 
00228 inline void BucketFile::seek (Int offset)
00229     { seek (Int64(offset)); }
00230 
00231 inline Bool BucketFile::isCached() const
00232     { return !isMapped_p && bufSize_p==0; }
00233 inline Bool BucketFile::isMapped() const
00234     { return isMapped_p; }
00235 inline Bool BucketFile::isBuffered() const
00236     { return bufSize_p>0; }
00237 
00238 
00239 } //# NAMESPACE CASACORE - END
00240 
00241 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1