casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
StandardStMan.h
Go to the documentation of this file.
00001 //# StandardStMan.h: The Standard Storage Manager
00002 //# Copyright (C) 2000,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: StandardStMan.h 20551 2009-03-25 00:11:33Z Malte.Marquarding $
00027 
00028 #ifndef TABLES_STANDARDSTMAN_H
00029 #define TABLES_STANDARDSTMAN_H
00030 
00031 //# Includes
00032 #include <casa/aips.h>
00033 #include <tables/Tables/SSMBase.h>
00034 
00035 
00036 namespace casa { //# NAMESPACE CASA - BEGIN
00037 
00038 // <summary>
00039 // The Standard Storage Manager
00040 // </summary>
00041 
00042 // <use visibility=export>
00043 
00044 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tStandardStMan.cc">
00045 // </reviewed>
00046 
00047 // <prerequisite>
00048 //# Classes you should understand before using this one.
00049 //   <li> The Table Data Managers concept as described in module file
00050 //        <linkto module="Tables:Data Managers">Tables.h</linkto>
00051 //   <li> <linkto class=ROStandardStManAccessor>
00052 //        ROStandardStManAccessor</linkto>
00053 //        for a discussion of the cache size
00054 // </prerequisite>
00055 
00056 // <etymology>
00057 // StandardStMan is the data manager which stores the data in a
00058 // standard way. I.e. it does not use special techniques like
00059 // other storage managers do.
00060 // </etymology>
00061 
00062 // <synopsis>
00063 // StandardStMan is meant as the storage manager to be used standardly.
00064 // Other storage managers like
00065 // <linkto class=IncrementalStMan>IncrementalStMan</linkto> and the
00066 // <linkto class=TiledStMan>TiledStMan</linkto> derivatives should
00067 // only be used when appropriate.
00068 // <br>
00069 // Like the other storage managers StandardStMan uses
00070 // <linkto class=BucketCache>bucket-based</linkto> access to its data.
00071 // where a bucket contains the number of columns and rows that fit best.
00072 // Variable length strings are stored in separate buckets because they do
00073 // not fit in the fixed bucket layout used for the other columns.
00074 // Only fixed length strings and strings <= 8 characters are stored directly.
00075 // Note that, in fact, fixed length string means maximum length strings.
00076 // It can be set using the <src>setMaxLength</src> function in
00077 // class <linkto class=ColumnDesc>ColumnDesc</linkto> or
00078 // class <linkto class=BaseColumnDesc>BaseColumnDesc</linkto>.
00079 // <p>
00080 // The file size is at least the size of a bucket, even if only the table
00081 // contains only a few rows, thus uses only a fraction of a bucket.
00082 // The default bucketsize is 32 rows. This means that if it is known
00083 // in advance that the table will contain many more rows, it might make
00084 // sense to construct the StandardStMan with a larger bucketsize.
00085 // <p>
00086 // StandardStMan is a robust storage manager. Care has been taken
00087 // that its index cannot be corrupted in case of exceptions like
00088 // device full or crash.
00089 // <p>
00090 // StandardStMan supports the following functionality:
00091 // <ol>
00092 //  <li> Removal of rows. This leaves some empty space in a bucket.
00093 //       An empty bucket will be reused.
00094 //  <li> Addition of rows. This is always done in the last bucket
00095 //       and a new bucket is added when needed.
00096 //  <li> Removal of a column. This also leaves empty space, which will
00097 //       be reused when a newly added column fits in it.
00098 //  <li> Addition of a column. If available, empty column space is used.
00099 //       Otherwise it creates as many new buckets as needed.
00100 // </ol>
00101 // All direct data (scalars and direct arrays) is stored in the main file.
00102 // Indirect arrays (except strings) are stored in a second file.
00103 // Indirect string arrays are also stored in the main file, because in
00104 // that way frequently rewriting indirect strings arrays wastes far
00105 // less space.
00106 // <p>
00107 // As said above all string arrays and variable length scalar strings
00108 // are stored in separate string buckets. 
00109 // </synopsis>
00110 
00111 // <motivation>
00112 // StManAipsIO is the standard storage manager used so far.
00113 // Its major drawback is that it is memory based which makes it
00114 // not usable for large tables. Furthermore it is not a very robust
00115 // storage manager. When a system crashes, tables might get corrupted.
00116 // <br>
00117 // These drawbacks have been adressed in this new StandardStman.
00118 // It uses a bucket-based access scheme and makes sure that its
00119 // indices are stored in a way that they can hardly get corrupted.
00120 // </motivation>
00121 
00122 // <example>
00123 // The following example shows how to create a table and how to attach
00124 // the storage manager to some columns.
00125 // <srcblock>
00126 //   SetupNewTable newtab("name.data", tableDesc, Table::New);
00127 //   StandardStMan stman;                     // define storage manager
00128 //   newtab.bindColumn ("column1", stman);    // bind column to st.man.
00129 //   newtab.bindColumn ("column2", stman);    // bind column to st.man.
00130 //   Table tab(newtab);                       // actually create table
00131 // </srcblock>
00132 //
00133 // The following example shows how to create a StandardStMan storage
00134 // manager for a table with 16 rows. By giving the (expected) nr of rows
00135 // to the storage manager, it can optimize its bucket size.
00136 // <srcblock>
00137 //   SetupNewTable newtab("name.data", tableDesc, Table::New);
00138 //   StandardStMan stman(-16);
00139 //   newtab.bindAll ("column1", stman);       // bind all columns to st.man.
00140 //   Table tab(newtab);                       // actually create table
00141 // </srcblock>
00142 // </example>
00143 
00144 //# <todo asof="$DATE:$">
00145 //# A List of bugs, limitations, extensions or planned refinements.
00146 //# </todo>
00147 
00148 
00149 class StandardStMan : public SSMBase
00150 {
00151 public:
00152     // Create a Standard storage manager with the given name.
00153     // If no name is used, it is set to "SSM"
00154     // The name can be used to construct a
00155     // <linkto class=ROStandardStManAccessor>ROStandardStManAccessor
00156     // </linkto> object (e.g. to set the cache size).
00157     // <br>
00158     // The cache size has to be given in buckets.
00159     // <br>
00160     // The bucket size can be given in 2 ways:
00161     // <br>- A positive number gives the bucket size in bytes.
00162     // The number of rows per bucket will be calculated from it.
00163     // <br>- A negative number gives the number of rows per bucket.
00164     // The bucket size in bytes will be calculated from it.
00165     // Note that in this way the maximum bucketsize is 32768 (minimum is 128).
00166     // <br>- The default 0 means that 32 rows will be stored in a bucket.
00167     // <br>Note that the default is only suitable for small tables.
00168     // In general it makes sense to give the expected number of table rows.
00169     // In that way the buckets will be small enough for small tables
00170     // and not too small for large tables.
00171     // <group>
00172     explicit StandardStMan (Int bucketSize = 0,
00173                             uInt cacheSize = 1);
00174     explicit StandardStMan (const String& dataManagerName,
00175                             Int bucketSize = 0,
00176                             uInt cacheSize = 1);
00177     // </group>
00178 
00179     ~StandardStMan();
00180 
00181 private:
00182     // Copy constructor cannot be used.
00183     StandardStMan (const StandardStMan& that);
00184 
00185     // Assignment cannot be used.
00186     StandardStMan& operator= (const StandardStMan& that);
00187 };
00188 
00189 
00190 
00191 } //# NAMESPACE CASA - END
00192 
00193 #endif