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