TableLock.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1