casacore
Loading...
Searching...
No Matches
PlainTable.h
Go to the documentation of this file.
1//# PlainTable.h: Class defining a plain regular table
2//# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2001,2002,2003
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_PLAINTABLE_H
29#define TABLES_PLAINTABLE_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/tables/Tables/BaseTable.h>
35#include <casacore/tables/Tables/TableCache.h>
36#include <casacore/tables/Tables/TableRecord.h>
37#include <casacore/tables/Tables/TableSyncData.h>
38#include <casacore/tables/DataMan/TSMOption.h>
39#include <casacore/casa/IO/AipsIO.h>
40
41namespace casacore { //# NAMESPACE CASACORE - BEGIN
42
43//# Forward Declarations
44class SetupNewTable;
45class TableLock;
46class TableLockData;
47class ColumnSet;
48class IPosition;
49class AipsIO;
50class MemoryIO;
51
52
53// <summary>
54// Class defining a plain regular table
55// </summary>
56
57// <use visibility=local>
58
59// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
60// </reviewed>
61
62// <prerequisite>
63//# Classes you should understand before using this one.
64// <li> BaseTable
65// <li> BaseColumn
66// </prerequisite>
67
68// <etymology>
69// PlainTable represents a plain regular table. This is opposed to a
70// RefTable, which is a view on a PlainTable.
71// </etymology>
72
73// <synopsis>
74// PlainTable is a table consisting of a keyword set and a number of
75// filled and virtual columns. The table control information and the
76// keyword set is stored in an AipsIO file. The data in the filled columns
77// are stored separately by storage managers.
78// <br> The PlainTable class structure is shown in this
79// <a href="PlainTable.drawio.svg.html">UML diagram</a>.
80// </synopsis>
81
82// <todo asof="$DATE:$">
83//# A List of bugs, limitations, extensions or planned refinements.
84// <li> notify RefTable's when deleting rows
85// </todo>
86
87class PlainTable : public BaseTable
88{
89public:
90
91 // Construct the object for a new table.
92 // It creates storage manager(s) for unbound columns and initializes
93 // all storage managers. The given number of rows is stored in
94 // the table and initialized if the flag is set.
95 PlainTable (SetupNewTable&, rownr_t nrrow, Bool initialize,
96 const TableLock& lockOptions, int endianFormat,
97 const TSMOption& tsmOption);
98
99#ifdef HAVE_MPI
100 // MPI version of the constructor
101 PlainTable (MPI_Comm mpiComm, SetupNewTable&, rownr_t nrrow,
102 Bool initialize, const TableLock& lockOptions,
103 int endianFormat, const TSMOption& tsmOption);
104#endif
105
106 // Common part of the constructor shared by MPI and non-MPI
107 void PlainTableCommon (SetupNewTable&, rownr_t nrrow, Bool initialize,
108 const TableLock& lockOptions, int endianFormat,
109 const TSMOption& tsmOption);
110
111 // Construct the object for an existing table.
112 // It opens the table file, reads the table control information
113 // and creates and initializes the required storage managers.
114 PlainTable (AipsIO&, uInt version, const String& name, const String& type,
115 rownr_t nrrow, int option, const TableLock& lockOptions,
116 const TSMOption& tsmOption, Bool addToCache, uInt locknr);
117
118 // The destructor flushes (i.e. writes) the table if it is opened
119 // for output and not marked for delete.
120 virtual ~PlainTable();
121
122 // Return the layout of a table (i.e. description and #rows).
123 // This function has the advantage that only the minimal amount of
124 // information required is read from the table, thus it is much
125 // faster than a normal table open.
126 // <br> The number of rows is returned. The description of the table
127 // is stored in desc (its contents will be overwritten).
128 static void getLayout (TableDesc& desc, AipsIO& ios);
129
130 // Try to reopen the table for read/write access.
131 // An exception is thrown if the table is not writable.
132 // Nothing is done if the table is already open for read/write.
133 virtual void reopenRW();
134
135 // Is the table stored in big or little endian format?
136 virtual Bool asBigEndian() const;
137
138 // Get the storage option used for the table.
139 virtual const StorageOption& storageOption() const;
140
141 // Is the table in use (i.e. open) in another process?
142 // If <src>checkSubTables</src> is set, it is also checked if
143 // a subtable is used in another process.
144 virtual Bool isMultiUsed (Bool checkSubTables) const;
145
146 // Get the locking info.
147 virtual const TableLock& lockOptions() const;
148
149 // Merge the given lock info with the existing one.
150 virtual void mergeLock (const TableLock& lockOptions);
151
152 // Has this process the read or write lock, thus can the table
153 // be read or written safely?
155
156 // Try to lock the table for read or write access.
157 virtual Bool lock (FileLocker::LockType, uInt nattempts);
158
159 // Unlock the table. This will also synchronize the table data,
160 // thus force the data to be written to disk.
161 virtual void unlock();
162
163 // Do a release of an AutoLock when the inspection interval has expired.
164 // <src>always=True</src> means that the inspection is always done,
165 // thus not every 25th call or so.
166 void autoReleaseLock (Bool always = False);
167
168 // Flush the table, i.e. write it to disk.
169 // Nothing will be done if the table is not writable.
170 // A flush can be executed at any time.
171 // When a table is marked for delete, the destructor will remove
172 // files written by intermediate flushes.
173 // Note that if necessary the destructor will do an implicit flush,
174 // unless it is executed due to an exception.
175 virtual void flush (Bool fsync, Bool recursive);
176
177 // Resync the Table object with the table file.
178 virtual void resync();
179
180 // Get the modify counter.
181 virtual uInt getModifyCounter() const;
182
183 // Set the table to being changed.
184 virtual void setTableChanged();
185
186 // Convert a Table option to an AipsIO file option.
187 // This is used by storage managers.
189
190 // Test if the table is opened as writable.
191 virtual Bool isWritable() const;
192
193 // Get the actual table description.
194 virtual TableDesc actualTableDesc() const;
195
196 // Get the data manager info.
197 virtual Record dataManagerInfo() const;
198
199 // Get readonly access to the table keyword set.
201
202 // Get read/write access to the table keyword set.
203 // This requires that the table is locked (or it gets locked
204 // when using AutoLocking mode).
206
207 // Get a column object using its index.
208 virtual BaseColumn* getColumn (uInt columnIndex) const;
209
210 // Get a column object using its name.
211 virtual BaseColumn* getColumn (const String& columnName) const;
212
213 // Test if it is possible to add a row to this table.
214 virtual Bool canAddRow() const;
215
216 // Add one or more rows and possibly initialize them.
217 // This will fail for tables not supporting addition of rows.
218 virtual void addRow (rownr_t nrrow, Bool initialize);
219
220 // Test if it is possible to remove a row from this table.
221 virtual Bool canRemoveRow() const;
222
223 // Remove the given row.
224 // This will fail for tables not supporting removal of rows.
225 virtual void removeRow (rownr_t rownr);
226
227 // Add a column to the table.
228 // The last Bool argument is not used in PlainTable, but can be used in
229 // other classes derived from BaseTable.
230 // <group>
231 virtual void addColumn (const ColumnDesc& columnDesc, Bool);
232 virtual void addColumn (const ColumnDesc& columnDesc,
233 const String& dataManager, Bool byName, Bool);
234 virtual void addColumn (const ColumnDesc& columnDesc,
235 const DataManager& dataManager, Bool);
236 virtual void addColumn (const TableDesc& tableDesc,
237 const DataManager& dataManager, Bool);
238 // </group>
239
240 // Test if columns can be removed.
241 virtual Bool canRemoveColumn (const Vector<String>& columnNames) const;
242
243 // Remove columns.
244 virtual void removeColumn (const Vector<String>& columnNames);
245
246 // Test if a column can be renamed (yes).
247 virtual Bool canRenameColumn (const String& columnName) const;
248
249 // Rename a column.
250 virtual void renameColumn (const String& newName, const String& oldName);
251
252 // Rename a hypercolumn.
253 virtual void renameHypercolumn (const String& newName,
254 const String& oldName);
255
256 // Find the data manager with the given name or for the given column.
257 virtual DataManager* findDataManager (const String& name,
258 Bool byColumn) const;
259
260
261 // Get access to the TableCache.
263 { return theirTableCache; }
264
265private:
266 // Copy constructor is forbidden, because copying a table requires
267 // some more knowledge (like table name of result).
268 // Declaring it private, makes it unusable.
270
271 // Assignment is forbidden, because copying a table requires
272 // some more knowledge (like table name of result).
273 // Declaring it private, makes it unusable.
275
276 // Close the object which is called by the destructor.
278
279 // Rename the subtables (used by rename function).
280 virtual void renameSubTables (const String& newName,
281 const String& oldName);
282
283 // The callback function when a lock is released.
284 // This flushes the table data, writes the synchronization data
285 // into the MemoryIO object, and returns a pointer to it.
286 // <group>
287 static MemoryIO* releaseCallBack (void* plainTableObject, Bool always);
289 // </group>
290
291 // When needed, write the table control information in an AipsIO file.
292 // Tell the storage managers to flush and close their files.
293 // It returns a switch to tell if the table control information has
294 // been written.
295 Bool putFile (Bool always);
296
297 // Synchronize the table after having acquired a lock which says
298 // that main table data has changed.
299 // It check if the columns did not change.
300 // It updates the table and column keywords.
301 void syncTable();
302
303 // Determine and set the endian format (big or little).
304 void setEndian (int endianFormat);
305
306 // Throw an exception if the table is not writable.
307 void checkWritable (const char* func) const;
308
309
310 CountedPtr<ColumnSet> colSetPtr_p; //# pointer to set of columns
311 Bool tableChanged_p; //# Has the main data changed?
312 Bool addToCache_p; //# Is table added to cache?
313 TableLockData* lockPtr_p; //# pointer to lock object
314 TableSyncData lockSync_p; //# table synchronization
315 Bool bigEndian_p; //# True = big endian canonical
316 //# False = little endian canonical
318 //# cache of open (plain) tables
320};
321
322
323
324} //# NAMESPACE CASACORE - END
325
326#endif
const TableDesc & tableDesc() const
Get the table description.
Definition BaseTable.h:272
int tableOption() const
Get the table option.
Definition BaseTable.h:253
OpenOption
Define the possible ByteIO open options.
Definition ByteIO.h:65
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
Abstract base class for a data manager.
LockType
Define the possible lock types.
Definition FileLocker.h:95
TableSyncData lockSync_p
Definition PlainTable.h:314
virtual const TableLock & lockOptions() const
Get the locking info.
static MemoryIO * releaseCallBack(void *plainTableObject, Bool always)
The callback function when a lock is released.
virtual void mergeLock(const TableLock &lockOptions)
Merge the given lock info with the existing one.
virtual void addColumn(const TableDesc &tableDesc, const DataManager &dataManager, Bool)
virtual Bool isMultiUsed(Bool checkSubTables) const
Is the table in use (i.e.
virtual void setTableChanged()
Set the table to being changed.
virtual DataManager * findDataManager(const String &name, Bool byColumn) const
Find the data manager with the given name or for the given column.
PlainTable(MPI_Comm mpiComm, SetupNewTable &, rownr_t nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
MPI version of the constructor.
void setEndian(int endianFormat)
Determine and set the endian format (big or little).
void checkWritable(const char *func) const
Throw an exception if the table is not writable.
virtual void removeColumn(const Vector< String > &columnNames)
Remove columns.
virtual Bool canRemoveColumn(const Vector< String > &columnNames) const
Test if columns can be removed.
CountedPtr< ColumnSet > colSetPtr_p
Definition PlainTable.h:310
void syncTable()
Synchronize the table after having acquired a lock which says that main table data has changed.
virtual Bool canRenameColumn(const String &columnName) const
Test if a column can be renamed (yes).
void PlainTableCommon(SetupNewTable &, rownr_t nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
Common part of the constructor shared by MPI and non-MPI.
virtual void renameColumn(const String &newName, const String &oldName)
Rename a column.
virtual uInt getModifyCounter() const
Get the modify counter.
virtual BaseColumn * getColumn(uInt columnIndex) const
Get a column object using its index.
void autoReleaseLock(Bool always=False)
Do a release of an AutoLock when the inspection interval has expired.
MemoryIO * doReleaseCallBack(Bool always)
Bool putFile(Bool always)
When needed, write the table control information in an AipsIO file.
virtual void renameSubTables(const String &newName, const String &oldName)
Rename the subtables (used by rename function).
virtual void renameHypercolumn(const String &newName, const String &oldName)
Rename a hypercolumn.
virtual void resync()
Resync the Table object with the table file.
virtual Record dataManagerInfo() const
Get the data manager info.
static TableCache theirTableCache
Definition PlainTable.h:319
virtual Bool isWritable() const
Test if the table is opened as writable.
static ByteIO::OpenOption toAipsIOFoption(int tableOption)
Convert a Table option to an AipsIO file option.
virtual void addColumn(const ColumnDesc &columnDesc, const DataManager &dataManager, Bool)
virtual void addColumn(const ColumnDesc &columnDesc, const String &dataManager, Bool byName, Bool)
virtual Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
PlainTable(const PlainTable &)
Copy constructor is forbidden, because copying a table requires some more knowledge (like table name ...
PlainTable(AipsIO &, uInt version, const String &name, const String &type, rownr_t nrrow, int option, const TableLock &lockOptions, const TSMOption &tsmOption, Bool addToCache, uInt locknr)
Construct the object for an existing table.
virtual void flush(Bool fsync, Bool recursive)
Flush the table, i.e.
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Try to lock the table for read or write access.
static void getLayout(TableDesc &desc, AipsIO &ios)
Return the layout of a table (i.e.
virtual TableRecord & keywordSet()
Get readonly access to the table keyword set.
PlainTable & operator=(const PlainTable &)
Assignment is forbidden, because copying a table requires some more knowledge (like table name of res...
virtual BaseColumn * getColumn(const String &columnName) const
Get a column object using its name.
virtual TableDesc actualTableDesc() const
Get the actual table description.
virtual void removeRow(rownr_t rownr)
Remove the given row.
virtual void reopenRW()
Try to reopen the table for read/write access.
virtual void addColumn(const ColumnDesc &columnDesc, Bool)
Add a column to the table.
virtual void unlock()
Unlock the table.
virtual TableRecord & rwKeywordSet()
Get read/write access to the table keyword set.
virtual const StorageOption & storageOption() const
Get the storage option used for the table.
virtual Bool canRemoveRow() const
Test if it is possible to remove a row from this table.
virtual ~PlainTable()
The destructor flushes (i.e.
virtual void addRow(rownr_t nrrow, Bool initialize)
Add one or more rows and possibly initialize them.
virtual Bool canAddRow() const
Test if it is possible to add a row to this table.
PlainTable(SetupNewTable &, rownr_t nrrow, Bool initialize, const TableLock &lockOptions, int endianFormat, const TSMOption &tsmOption)
Construct the object for a new table.
virtual Bool asBigEndian() const
Is the table stored in big or little endian format?
TableLockData * lockPtr_p
Definition PlainTable.h:313
static TableCache & tableCache()
Get access to the TableCache.
Definition PlainTable.h:262
void closeObject()
Close the object which is called by the destructor.
Create a new table - define shapes, data managers, etc.
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
const Bool False
Definition aipstype.h:44
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition aipsxtype.h:46