00001 //# TableLock.h: Class to hold table lock options 00002 //# Copyright (C) 1997,1998,2000,2001 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$ 00027 00028 #ifndef TABLES_TABLELOCK_H 00029 #define TABLES_TABLELOCK_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/casa/IO/LockFile.h> 00035 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 // <summary> 00040 // Class to hold table lock options. 00041 // </summary> 00042 00043 // <use visibility=local> 00044 00045 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tTable" demos=""> 00046 // </reviewed> 00047 00048 // <prerequisite> 00049 // <li> class <linkto class=Table>Table</linkto> 00050 // <li> class <linkto class=LockFile>LockFile</linkto> 00051 // </prerequisite> 00052 00053 // <synopsis> 00054 // This class keeps the Table lock options. 00055 // Currently these are the LockingOption and the inspection interval. 00056 // <p> 00057 // It also keeps the <src>LockFile</src> object used to do the 00058 // actual locking/unlocking. 00059 00060 // <motivation> 00061 // Encapsulate Table locking info. 00062 // </motivation> 00063 00064 00065 class TableLock 00066 { 00067 public: 00068 // Define the possible table locking options. 00069 // They offer the user the possibility to lock and synchronize access 00070 // to the table. A lot of locking degrades table performance; not only 00071 // because acquiring/releasing locks takes time, but especially 00072 // because table data has to be synchronized (thus written to disk) 00073 // when a lock is released. Otherwise the other processes see data 00074 // which is not up-to-date. 00075 enum LockOption { 00076 // The table is permanently locked. 00077 // A lock is set at the beginning and only released when 00078 // the table is closed. A read lock is used when the table is 00079 // opened for readonly; otherwise a write lock is used. 00080 // This means that multiple readers are possible. 00081 // The Table constructor exits with an exception when the 00082 // lock cannot be acquired. 00083 PermanentLocking, 00084 // The same as above, but the table constructor waits 00085 // until the lock gets available. 00086 PermanentLockingWait, 00087 // The system takes care of acquiring/releasing locks. 00088 // In principle it keeps the table locked, but from time to 00089 // time (defined by the inspection interval) it is checked whether 00090 // another process wants to access the table. If so, the lock 00091 // is released and probably re-acquired later. 00092 // This mode is the default mode. 00093 AutoLocking, 00094 // The user is taking care of locking the table by means 00095 // of the Table functions <src>lock</src> and <src>unlock</src>. 00096 // In this way transaction processing can be implemented. 00097 UserLocking, 00098 // The system takes care of acquiring/releasing locks. 00099 // It is similar to AutoLocking, but no locks are needed for 00100 // reading. 00101 AutoNoReadLocking, 00102 // The user is taking care of locking the table by means 00103 // of the Table functions <src>lock</src> and <src>unlock</src>. 00104 // It is similar to UserLocking, but no locks are needed for 00105 // reading. 00106 UserNoReadLocking, 00107 // Do not do any locking at all. This should be used with care 00108 // because concurrent access might result in table corruption. 00109 NoLocking, 00110 // This is the default locking option. 00111 // It means that AutoLocking will be used if the table is not 00112 // opened yet. Otherwise the locking options of the PlainTable 00113 // object already in use will be used. 00114 DefaultLocking 00115 }; 00116 00117 // Construct with given option and interval. 00118 // The default <src>LockOption</src> is <src>AutoLocking</src>. 00119 // In case of AutloLocking the inspection interval defines how often 00120 // the table system checks if another process needs a lock on the table. 00121 // It defaults to 5 seconds. 00122 // The maxWait defines the maximum number of seconds the table system 00123 // waits when acquiring a lock in AutoLocking mode. The default 00124 // is 0 seconds meaning indefinitely. 00125 // <group> 00126 TableLock (LockOption option = DefaultLocking); 00127 TableLock (LockOption option, double inspectionInterval, uInt maxWait = 0); 00128 // </group> 00129 00130 // Copy constructor. 00131 TableLock (const TableLock& that); 00132 00133 // Assignment. 00134 TableLock& operator= (const TableLock& that); 00135 00136 // Merge that TableLock with this TableLock object by taking the 00137 // maximum option and minimum inspection interval. 00138 // The option order (ascending) is UserLocking, AutoLocking, 00139 // PermanentLocking. 00140 // When an interval was defaulted, it is not taken into account. 00141 // An option DefaultLocking is not taken into account. 00142 void merge (const TableLock& that); 00143 00144 // Get the locking option. 00145 LockOption option() const; 00146 00147 // Is read locking needed? 00148 Bool readLocking() const; 00149 00150 // Is permanent locking used? 00151 Bool isPermanent() const; 00152 00153 // Get the inspection interval. 00154 double interval() const; 00155 00156 // Get the maximum wait period in AutoLocking mode. 00157 uInt maxWait() const; 00158 00159 // Is table locking disabled (because AIPS_TABLE_NOLOCKING was set)? 00160 static Bool lockingDisabled(); 00161 00162 00163 private: 00164 LockOption itsOption; 00165 Bool itsReadLocking; 00166 uInt itsMaxWait; 00167 double itsInterval; 00168 Bool itsIsDefaultLocking; 00169 Bool itsIsDefaultInterval; 00170 00171 00172 // Set itsOption and itsReadLocking when needed. 00173 void init(); 00174 }; 00175 00176 00177 00178 inline TableLock::LockOption TableLock::option() const 00179 { 00180 return itsOption; 00181 } 00182 00183 inline Bool TableLock::readLocking() const 00184 { 00185 return itsReadLocking; 00186 } 00187 00188 inline Bool TableLock::isPermanent() const 00189 { 00190 return (itsOption == PermanentLocking 00191 || itsOption == PermanentLockingWait); 00192 } 00193 00194 inline double TableLock::interval() const 00195 { 00196 return itsInterval; 00197 } 00198 00199 inline uInt TableLock::maxWait() const 00200 { 00201 return itsMaxWait; 00202 } 00203 00204 00205 00206 } //# NAMESPACE CASACORE - END 00207 00208 #endif