casacore
StandardStMan.h
Go to the documentation of this file.
1 //# StandardStMan.h: The Standard Storage Manager
2 //# Copyright (C) 2000,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TABLES_STANDARDSTMAN_H
29 #define TABLES_STANDARDSTMAN_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/tables/DataMan/SSMBase.h>
34 
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <summary>
39 // The Standard Storage Manager
40 // </summary>
41 
42 // <use visibility=export>
43 
44 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tStandardStMan.cc">
45 // </reviewed>
46 
47 // <prerequisite>
48 //# Classes you should understand before using this one.
49 // <li> The Table Data Managers concept as described in module file
50 // <linkto module="Tables:Data Managers">Tables.h</linkto>
51 // <li> <linkto class=ROStandardStManAccessor>
52 // ROStandardStManAccessor</linkto>
53 // for a discussion of the cache size
54 // </prerequisite>
55 
56 // <etymology>
57 // StandardStMan is the data manager which stores the data in a
58 // standard way. I.e. it does not use special techniques like
59 // other storage managers do.
60 // </etymology>
61 
62 // <synopsis>
63 // StandardStMan is meant as the storage manager to be used standardly.
64 // Other storage managers like
65 // <linkto class=IncrementalStMan>IncrementalStMan</linkto> and the
66 // <linkto class=TiledStMan>TiledStMan</linkto> derivatives should
67 // only be used when appropriate.
68 // <br>
69 // Like the other storage managers StandardStMan uses
70 // <linkto class=BucketCache>bucket-based</linkto> access to its data.
71 // where a bucket contains the number of columns and rows that fit best.
72 // Variable length strings are stored in separate buckets because they do
73 // not fit in the fixed bucket layout used for the other columns.
74 // Only fixed length strings and strings <= 8 characters are stored directly.
75 // Note that, in fact, fixed length string means maximum length strings.
76 // It can be set using the <src>setMaxLength</src> function in
77 // class <linkto class=ColumnDesc>ColumnDesc</linkto> or
78 // class <linkto class=BaseColumnDesc>BaseColumnDesc</linkto>.
79 // <p>
80 // The file size is at least the size of a bucket, even if only the table
81 // contains only a few rows, thus uses only a fraction of a bucket.
82 // The default bucketsize is 32 rows. This means that if it is known
83 // in advance that the table will contain many more rows, it might make
84 // sense to construct the StandardStMan with a larger bucketsize.
85 // <p>
86 // StandardStMan is a robust storage manager. Care has been taken
87 // that its index cannot be corrupted in case of exceptions like
88 // device full or crash.
89 // <p>
90 // StandardStMan supports the following functionality:
91 // <ol>
92 // <li> Removal of rows. This leaves some empty space in a bucket.
93 // An empty bucket will be reused.
94 // <li> Addition of rows. This is always done in the last bucket
95 // and a new bucket is added when needed.
96 // <li> Removal of a column. This also leaves empty space, which will
97 // be reused when a newly added column fits in it.
98 // <li> Addition of a column. If available, empty column space is used.
99 // Otherwise it creates as many new buckets as needed.
100 // </ol>
101 // All direct data (scalars and direct arrays) is stored in the main file.
102 // Indirect arrays (except strings) are stored in a second file.
103 // Indirect string arrays are also stored in the main file, because in
104 // that way frequently rewriting indirect strings arrays wastes far
105 // less space.
106 // <p>
107 // As said above all string arrays and variable length scalar strings
108 // are stored in separate string buckets.
109 // </synopsis>
110 
111 // <motivation>
112 // StManAipsIO is the standard storage manager used so far.
113 // Its major drawback is that it is memory based which makes it
114 // not usable for large tables. Furthermore it is not a very robust
115 // storage manager. When a system crashes, tables might get corrupted.
116 // <br>
117 // These drawbacks have been adressed in this new StandardStman.
118 // It uses a bucket-based access scheme and makes sure that its
119 // indices are stored in a way that they can hardly get corrupted.
120 // </motivation>
121 
122 // <example>
123 // The following example shows how to create a table and how to attach
124 // the storage manager to some columns.
125 // <srcblock>
126 // SetupNewTable newtab("name.data", tableDesc, Table::New);
127 // StandardStMan stman; // define storage manager
128 // newtab.bindColumn ("column1", stman); // bind column to st.man.
129 // newtab.bindColumn ("column2", stman); // bind column to st.man.
130 // Table tab(newtab); // actually create table
131 // </srcblock>
132 //
133 // The following example shows how to create a StandardStMan storage
134 // manager for a table with 16 rows. By giving the (expected) nr of rows
135 // to the storage manager, it can optimize its bucket size.
136 // <srcblock>
137 // SetupNewTable newtab("name.data", tableDesc, Table::New);
138 // StandardStMan stman(-16);
139 // newtab.bindAll ("column1", stman); // bind all columns to st.man.
140 // Table tab(newtab); // actually create table
141 // </srcblock>
142 // </example>
143 
144 //# <todo asof="$DATE:$">
145 //# A List of bugs, limitations, extensions or planned refinements.
146 //# </todo>
147 
148 
149 class StandardStMan : public SSMBase
150 {
151 public:
152  // Create a Standard storage manager with the given name.
153  // If no name is used, it is set to "SSM"
154  // The name can be used to construct a
155  // <linkto class=ROStandardStManAccessor>ROStandardStManAccessor
156  // </linkto> object (e.g. to set the cache size).
157  // <br>
158  // The cache size has to be given in buckets.
159  // <br>
160  // The bucket size can be given in 2 ways:
161  // <br>- A positive number gives the bucket size in bytes.
162  // The number of rows per bucket will be calculated from it.
163  // <br>- A negative number gives the number of rows per bucket.
164  // The bucket size in bytes will be calculated from it.
165  // Note that in this way the maximum bucketsize is 32768 (minimum is 128).
166  // <br>- The default 0 means that 32 rows will be stored in a bucket.
167  // <br>Note that the default is only suitable for small tables.
168  // In general it makes sense to give the expected number of table rows.
169  // In that way the buckets will be small enough for small tables
170  // and not too small for large tables.
171  // <group>
172  explicit StandardStMan (Int bucketSize = 0,
173  uInt cacheSize = 1);
175  Int bucketSize = 0,
176  uInt cacheSize = 1);
177  // </group>
178 
180 
181 private:
182  // Copy constructor cannot be used.
184 
185  // Assignment cannot be used.
187 };
188 
189 
190 
191 } //# NAMESPACE CASACORE - END
192 
193 #endif
virtual String dataManagerName() const
Get the name given to the storage manager (in the constructor).
StandardStMan(Int bucketSize=0, uInt cacheSize=1)
Create a Standard storage manager with the given name.
StandardStMan(const StandardStMan &that)
Copy constructor cannot be used.
StandardStMan(const String &dataManagerName, Int bucketSize=0, uInt cacheSize=1)
StandardStMan & operator=(const StandardStMan &that)
Assignment cannot be used.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50