Документ взят из кэша поисковой машины. Адрес
оригинального документа
: http://www.atnf.csiro.au/computing/software/casacore/casacore-1.2.0/doc/html/ISMBase_8h_source.html
Дата изменения: Unknown Дата индексирования: Mon Feb 14 19:52:38 2011 Кодировка: |
00001 //# ISMBase.h: Base class of the Incremental Storage Manager 00002 //# Copyright (C) 1996,1997,1999,2000,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: ISMBase.h 20883 2010-04-27 06:02:21Z gervandiepen $ 00027 00028 #ifndef TABLES_ISMBASE_H 00029 #define TABLES_ISMBASE_H 00030 00031 00032 //# Includes 00033 #include <casa/aips.h> 00034 #include <tables/Tables/DataManager.h> 00035 #include <casa/Containers/Block.h> 00036 #include <casa/iosfwd.h> 00037 00038 namespace casa { //# NAMESPACE CASA - BEGIN 00039 00040 //# Forward declarations 00041 class BucketCache; 00042 class BucketFile; 00043 class ISMBucket; 00044 class ISMIndex; 00045 class ISMColumn; 00046 class StManArrayFile; 00047 00048 // <summary> 00049 // Base class of the Incremental Storage Manager 00050 // </summary> 00051 00052 // <use visibility=local> 00053 00054 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tIncrementalStMan.cc"> 00055 // </reviewed> 00056 00057 // <prerequisite> 00058 //# Classes you should understand before using this one. 00059 // <li> <linkto class=IncrementalStMan>IncrementalStMan</linkto> 00060 // <li> <linkto class=ISMColumn>ISMColumn</linkto> 00061 // </prerequisite> 00062 00063 // <etymology> 00064 // ISMBase is the base class of the Incremental Storage Manager. 00065 // </etymology> 00066 00067 // <synopsis> 00068 // The behaviour of this class is described in 00069 // <linkto class="IncrementalStMan:description">IncrementalStMan</linkto>. 00070 00071 // <motivation> 00072 // The public interface of ISMBase is quite large, because the other 00073 // internal ISM classes need these functions. To have a class with a 00074 // minimal interface for the normal user, class <src>IncrementalStMan</src> 00075 // is derived from it. 00076 // <br>IncrementalStMan needs an isA- instead of hasA-relation to be 00077 // able to bind columns to it in class <linkto class=SetupNewTable> 00078 // SetupNewTable</linkto>. 00079 // </motivation> 00080 00081 // <todo asof="$DATE:$"> 00082 //# A List of bugs, limitations, extensions or planned refinements. 00083 // <li> Removed AipsIO argument from open and close. 00084 // </todo> 00085 00086 00087 class ISMBase: public DataManager 00088 { 00089 public: 00090 // Create an incremental storage manager without a name. 00091 // The bucket size has to be given in bytes and the cache size in buckets. 00092 // The bucket size is checked or calculated as described in 00093 // IncrementalStMan.h. 00094 explicit ISMBase (uInt bucketSize = 0, Bool checkBucketSize = True, 00095 uInt cacheSize = 1); 00096 00097 // Create an incremental storage manager with the given name. 00098 // The bucket size has to be given in bytes and the cache size in buckets. 00099 // The bucket size is checked or calculated as described in 00100 // IncrementalStMan.h. 00101 ISMBase (const String& dataManagerName, 00102 uInt bucketSize, Bool checkBucketSize, uInt cacheSize); 00103 00104 // Create an incremental storage manager with the given name. 00105 // The specifications are in the record (as created by dataManagerSpec). 00106 ISMBase (const String& aDataManName, 00107 const Record& spec); 00108 00109 ~ISMBase(); 00110 00111 // Clone this object. 00112 // It does not clone ISMColumn objects possibly used. 00113 // The caller has to delete the newly created object. 00114 virtual DataManager* clone() const; 00115 00116 // Get the type name of the data manager (i.e. IncrementalStMan). 00117 virtual String dataManagerType() const; 00118 00119 // Get the name given to the storage manager (in the constructor). 00120 virtual String dataManagerName() const; 00121 00122 // Record a record containing data manager specifications. 00123 virtual Record dataManagerSpec() const; 00124 00125 // Get the version of the class. 00126 uInt version() const; 00127 00128 // Set the cache size (in buckets). 00129 // If <src>canExceedNrBuckets=True</src>, the given cache size can be 00130 // larger than the nr of buckets in the file. In this way the cache can 00131 // be made large enough for a future file extnsion. 00132 // Otherwise, it is limited to the actual number of buckets. This is useful 00133 // if one wants the entire file to be cached. 00134 void setCacheSize (uInt cacheSize, Bool canExceedNrBuckets); 00135 00136 // Get the current cache size (in buckets). 00137 uInt cacheSize() const; 00138 00139 // Clear the cache used by this storage manager. 00140 // It will flush the cache as needed and remove all buckets from it. 00141 void clearCache(); 00142 00143 // Show the statistics of all caches used. 00144 void showCacheStatistics (ostream& os) const; 00145 00146 // Get the bucket size (in bytes). 00147 uInt bucketSize() const; 00148 00149 // Get the size of a uInt in external format (can be canonical or local). 00150 uInt uIntSize() const; 00151 00152 // Get the bucket containing the given row. 00153 // Also return the first and last row of that bucket. 00154 // The bucket object is created and deleted by the caching mechanism. 00155 ISMBucket* getBucket (uInt rownr, uInt& bucketStartRow, 00156 uInt& bucketNrrow); 00157 00158 // Get the next bucket. 00159 // cursor=0 indicates the start of the iteration. 00160 // The first bucket returned is the bucket containing the rownr 00161 // given in bucketStartRow. 00162 // After each iteration BucketStartRow and bucketNrrow are set. 00163 // A 0 is returned when no more buckets. 00164 // The bucket object is created and deleted by the caching mechanism. 00165 ISMBucket* nextBucket (uInt& cursor, uInt& bucketStartRow, 00166 uInt& bucketNrrow); 00167 00168 // Get access to the temporary buffer. 00169 char* tempBuffer() const; 00170 00171 // Get a unique column number for the column 00172 // (it is only unique for this storage manager). 00173 // This is used by ISMColumnIndArr to create a unique file name. 00174 uInt uniqueNr(); 00175 00176 // Get the number of rows in this storage manager. 00177 uInt nrow() const; 00178 00179 // Can the storage manager add rows? (yes) 00180 virtual Bool canAddRow() const; 00181 00182 // Can the storage manager delete rows? (yes) 00183 virtual Bool canRemoveRow() const; 00184 00185 // Can the storage manager add columns? (not yet) 00186 virtual Bool canAddColumn() const; 00187 00188 // Can the storage manager delete columns? (not yet) 00189 virtual Bool canRemoveColumn() const; 00190 00191 // Make the object from the type name string. 00192 // This function gets registered in the DataManager "constructor" map. 00193 // The caller has to delete the object. 00194 static DataManager* makeObject (const String& dataManagerType, 00195 const Record& spec); 00196 00197 // Get access to the given column. 00198 ISMColumn& getColumn (uInt colnr); 00199 00200 // Add a bucket to the storage manager (i.e. to the cache). 00201 // The pointer is taken over. 00202 void addBucket (uInt rownr, ISMBucket* bucket); 00203 00204 // Make the current bucket in the cache dirty (i.e. something has been 00205 // changed in it and it needs to be written when removed from the cache). 00206 // (used by ISMColumn::putValue). 00207 void setBucketDirty(); 00208 00209 // Open (if needed) the file for indirect arrays with the given mode. 00210 // Return a pointer to the object. 00211 StManArrayFile* openArrayFile (ByteIO::OpenOption opt); 00212 00213 00214 private: 00215 // Copy constructor (only meant for clone function). 00216 ISMBase (const ISMBase& that); 00217 00218 // Assignment cannot be used. 00219 ISMBase& operator= (const ISMBase& that); 00220 00221 // (Re)create the index, file, and cache object. 00222 void recreate(); 00223 00224 // Flush and optionally fsync the data. 00225 // It returns a True status if it had to flush (i.e. if data have changed). 00226 virtual Bool flush (AipsIO&, Bool fsync); 00227 00228 // Let the storage manager create files as needed for a new table. 00229 // This allows a column with an indirect array to create its file. 00230 virtual void create (uInt nrrow); 00231 00232 // Open the storage manager file for an existing table, read in 00233 // the data, and let the ISMColumn objects read their data. 00234 virtual void open (uInt nrrow, AipsIO&); 00235 00236 // Resync the storage manager with the new file contents. 00237 // This is done by clearing the cache. 00238 virtual void resync (uInt nrrow); 00239 00240 // Reopen the storage manager files for read/write. 00241 virtual void reopenRW(); 00242 00243 // The data manager will be deleted (because all its columns are 00244 // requested to be deleted). 00245 // So clean up the things needed (e.g. delete files). 00246 virtual void deleteManager(); 00247 00248 // Let the storage manager initialize itself. 00249 // It is used by create and open. 00250 void init(); 00251 00252 // Add rows to the storage manager. 00253 // Per column it extends the interval for which the last value written 00254 // is valid. 00255 virtual void addRow (uInt nrrow); 00256 00257 // Delete a row from all columns. 00258 virtual void removeRow (uInt rownr); 00259 00260 // Do the final addition of a column. 00261 // The <src>DataManagerColumn</src> object has already been created 00262 // (by the <src>makeXXColumn</src> function) and added to 00263 // <src>colSet_p</src>. However, it still has to be added to the 00264 // data files, which is done by this function. It uses the 00265 // pointer to find the correct column in the <src>colSet_p</src>. 00266 virtual void addColumn (DataManagerColumn*); 00267 00268 // Remove a column from the data file and the <src>colSet_p</src>. 00269 // The <src>DataManagerColumn</src> object gets deleted.. 00270 virtual void removeColumn (DataManagerColumn*); 00271 00272 // Create a column in the storage manager on behalf of a table column. 00273 // The caller has to delete the newly created object. 00274 // <group> 00275 // Create a scalar column. 00276 virtual DataManagerColumn* makeScalarColumn (const String& name, 00277 int dataType, 00278 const String& dataTypeID); 00279 // Create a direct array column. 00280 virtual DataManagerColumn* makeDirArrColumn (const String& name, 00281 int dataType, 00282 const String& dataTypeID); 00283 // Create an indirect array column. 00284 virtual DataManagerColumn* makeIndArrColumn (const String& name, 00285 int dataType, 00286 const String& dataTypeID); 00287 // </group> 00288 00289 // Get the cache object. 00290 // This will construct the cache object if not present yet. 00291 // The cache object will be deleted by the destructor. 00292 BucketCache& getCache(); 00293 00294 // Get the index object. 00295 // This will construct the index object if not present yet. 00296 // The index object will be deleted by the destructor. 00297 ISMIndex& getIndex(); 00298 00299 // Construct the cache object (if not constructed yet). 00300 void makeCache(); 00301 00302 // Construct the index object (if not constructed yet) and read it. 00303 void makeIndex(); 00304 00305 // Read the index (at the end of the file). 00306 void readIndex(); 00307 00308 // Write the index (at the end of the file). 00309 void writeIndex(); 00310 00311 00312 //# Declare member variables. 00313 // Name of data manager. 00314 String dataManName_p; 00315 // The version of the class. 00316 uInt version_p; 00317 // The file containing the indirect arrays. 00318 StManArrayFile* iosfile_p; 00319 // Unique nr for column in this storage manager. 00320 uInt uniqnr_p; 00321 // The number of rows in the columns. 00322 uInt nrrow_p; 00323 // The assembly of all columns. 00324 PtrBlock<ISMColumn*> colSet_p; 00325 // The cache with the ISM buckets. 00326 BucketCache* cache_p; 00327 // The file containing all data. 00328 BucketFile* file_p; 00329 // The ISM bucket index. 00330 ISMIndex* index_p; 00331 // The persistent cache size. 00332 uInt persCacheSize_p; 00333 // The actual cache size. 00334 uInt cacheSize_p; 00335 // The initial number of buckets in the cache. 00336 uInt nbucketInit_p; 00337 // The nr of free buckets. 00338 uInt nFreeBucket_p; 00339 // The first free bucket. 00340 Int firstFree_p; 00341 // The bucket size. 00342 uInt bucketSize_p; 00343 // Check a positive bucketsize? 00344 Bool checkBucketSize_p; 00345 // Has the data changed since the last flush? 00346 Bool dataChanged_p; 00347 // The size of a uInt in external format (local or canonical). 00348 uInt uIntSize_p; 00349 // A temporary read/write buffer (also for other classes). 00350 char* tempBuffer_p; 00351 }; 00352 00353 00354 inline uInt ISMBase::version() const 00355 { 00356 return version_p; 00357 } 00358 00359 inline uInt ISMBase::cacheSize() const 00360 { 00361 return cacheSize_p; 00362 } 00363 00364 inline uInt ISMBase::uniqueNr() 00365 { 00366 return uniqnr_p++; 00367 } 00368 00369 inline uInt ISMBase::nrow() const 00370 { 00371 return nrrow_p; 00372 } 00373 00374 inline uInt ISMBase::bucketSize() const 00375 { 00376 return bucketSize_p; 00377 } 00378 00379 inline uInt ISMBase::uIntSize() const 00380 { 00381 return uIntSize_p; 00382 } 00383 00384 inline char* ISMBase::tempBuffer() const 00385 { 00386 return tempBuffer_p; 00387 } 00388 00389 inline BucketCache& ISMBase::getCache() 00390 { 00391 if (cache_p == 0) { 00392 makeCache(); 00393 } 00394 return *cache_p; 00395 } 00396 00397 inline ISMIndex& ISMBase::getIndex() 00398 { 00399 if (index_p == 0) { 00400 makeIndex(); 00401 } 00402 return *index_p; 00403 } 00404 00405 inline ISMColumn& ISMBase::getColumn (uInt colnr) 00406 { 00407 return *(colSet_p[colnr]); 00408 } 00409 00410 00411 00412 } //# NAMESPACE CASA - END 00413 00414 #endif