casacore
TableLock.h
Go to the documentation of this file.
1 //# TableLock.h: Class to hold table lock options
2 //# Copyright (C) 1997,1998,2000,2001
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_TABLELOCK_H
29 #define TABLES_TABLELOCK_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/IO/LockFile.h>
35 
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <summary>
40 // Class to hold table lock options.
41 // </summary>
42 
43 // <use visibility=local>
44 
45 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tTable" demos="">
46 // </reviewed>
47 
48 // <prerequisite>
49 // <li> class <linkto class=Table>Table</linkto>
50 // <li> class <linkto class=LockFile>LockFile</linkto>
51 // </prerequisite>
52 
53 // <synopsis>
54 // This class keeps the Table lock options.
55 // Currently these are the LockingOption and the inspection interval.
56 // <p>
57 // It also keeps the <src>LockFile</src> object used to do the
58 // actual locking/unlocking.
59 //
60 // It is possible to disable locking by building casacore with -DAIPS_TABLE_NOLOCKING
61 // or by setting the aipsrc variable table.nolocking=true.
62 
63 // <motivation>
64 // Encapsulate Table locking info.
65 // </motivation>
66 
67 
68 class TableLock
69 {
70 public:
71  // Define the possible table locking options.
72  // They offer the user the possibility to lock and synchronize access
73  // to the table. A lot of locking degrades table performance; not only
74  // because acquiring/releasing locks takes time, but especially
75  // because table data has to be synchronized (thus written to disk)
76  // when a lock is released. Otherwise the other processes see data
77  // which is not up-to-date.
78  //
79  // Building Casacore with -DTABLE_NOLOCKING or setting aipsrc variable
80  // table.nolocking=1 forces lock option NoLocking.
81  enum LockOption {
82  // The table is permanently locked.
83  // A lock is set at the beginning and only released when
84  // the table is closed. A read lock is used when the table is
85  // opened for readonly; otherwise a write lock is used.
86  // This means that multiple readers are possible.
87  // The Table constructor exits with an exception when the
88  // lock cannot be acquired.
90  // The same as above, but the table constructor waits
91  // until the lock gets available.
93  // The system takes care of acquiring/releasing locks.
94  // In principle it keeps the table locked, but from time to
95  // time (defined by the inspection interval) it is checked whether
96  // another process wants to access the table. If so, the lock
97  // is released and probably re-acquired later.
98  // This mode is the default mode.
100  // The user is taking care of locking the table by means
101  // of the Table functions <src>lock</src> and <src>unlock</src>.
102  // In this way transaction processing can be implemented.
104  // The system takes care of acquiring/releasing locks.
105  // It is similar to AutoLocking, but no locks are needed for
106  // reading.
108  // The user is taking care of locking the table by means
109  // of the Table functions <src>lock</src> and <src>unlock</src>.
110  // It is similar to UserLocking, but no locks are needed for
111  // reading.
113  // Do not do any locking at all. This should be used with care
114  // because concurrent access might result in table corruption.
116  // This is the default locking option.
117  // It means that AutoLocking will be used if the table is not
118  // opened yet. Otherwise the locking options of the PlainTable
119  // object already in use will be used.
121  };
122 
123  // Construct with given option and interval.
124  // The default <src>LockOption</src> is <src>AutoLocking</src>.
125  // In case of AutloLocking the inspection interval defines how often
126  // the table system checks if another process needs a lock on the table.
127  // It defaults to 5 seconds.
128  // The maxWait defines the maximum number of seconds the table system
129  // waits when acquiring a lock in AutoLocking mode. The default
130  // is 0 seconds meaning indefinitely.
131  // <group>
133  TableLock (LockOption option, double inspectionInterval, uInt maxWait = 0);
134  // </group>
135 
136  // Copy constructor.
137  TableLock (const TableLock& that);
138 
139  // Assignment.
141 
142  // Merge that TableLock with this TableLock object by taking the
143  // maximum option and minimum inspection interval.
144  // The option order (ascending) is UserLocking, AutoLocking,
145  // PermanentLocking.
146  // When an interval was defaulted, it is not taken into account.
147  // An option DefaultLocking is not taken into account.
148  void merge (const TableLock& that);
149 
150  // Get the locking option.
151  LockOption option() const;
152 
153  // Is read locking needed?
154  Bool readLocking() const;
155 
156  // Is permanent locking used?
157  Bool isPermanent() const;
158 
159  // Get the inspection interval.
160  double interval() const;
161 
162  // Get the maximum wait period in AutoLocking mode.
163  uInt maxWait() const;
164 
165  // Is table locking disabled (because AIPS_TABLE_NOLOCKING or table.nolocking is set)?
167 
168 
169 private:
173  double itsInterval;
176 
177 
178  // Set itsOption and itsReadLocking when needed.
179  void init();
180 };
181 
182 
183 
185 {
186  return itsOption;
187 }
188 
190 {
191  return itsReadLocking;
192 }
193 
195 {
196  return (itsOption == PermanentLocking
198 }
199 
200 inline double TableLock::interval() const
201 {
202  return itsInterval;
203 }
204 
205 inline uInt TableLock::maxWait() const
206 {
207  return itsMaxWait;
208 }
209 
210 
211 
212 } //# NAMESPACE CASACORE - END
213 
214 #endif
TableLock(LockOption option, double inspectionInterval, uInt maxWait=0)
LockOption
Define the possible table locking options.
Definition: TableLock.h:81
@ UserLocking
The user is taking care of locking the table by means of the Table functions lock and unlock.
Definition: TableLock.h:103
@ AutoLocking
The system takes care of acquiring/releasing locks.
Definition: TableLock.h:99
@ AutoNoReadLocking
The system takes care of acquiring/releasing locks.
Definition: TableLock.h:107
@ DefaultLocking
This is the default locking option.
Definition: TableLock.h:120
@ UserNoReadLocking
The user is taking care of locking the table by means of the Table functions lock and unlock.
Definition: TableLock.h:112
@ PermanentLocking
The table is permanently locked.
Definition: TableLock.h:89
@ NoLocking
Do not do any locking at all.
Definition: TableLock.h:115
@ PermanentLockingWait
The same as above, but the table constructor waits until the lock gets available.
Definition: TableLock.h:92
Bool isPermanent() const
Is permanent locking used?
Definition: TableLock.h:194
void init()
Set itsOption and itsReadLocking when needed.
TableLock(LockOption option=DefaultLocking)
Construct with given option and interval.
Bool readLocking() const
Is read locking needed?
Definition: TableLock.h:189
LockOption itsOption
Definition: TableLock.h:170
static Bool lockingDisabled()
Is table locking disabled (because AIPS_TABLE_NOLOCKING or table.nolocking is set)?
double interval() const
Get the inspection interval.
Definition: TableLock.h:200
uInt maxWait() const
Get the maximum wait period in AutoLocking mode.
Definition: TableLock.h:205
TableLock(const TableLock &that)
Copy constructor.
void merge(const TableLock &that)
Merge that TableLock with this TableLock object by taking the maximum option and minimum inspection i...
TableLock & operator=(const TableLock &that)
Assignment.
LockOption option() const
Get the locking option.
Definition: TableLock.h:184
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42