casacore
LatticeLocker.h
Go to the documentation of this file.
1 //# LatticeLocker.h: Class to hold a (user) lock on a lattice
2 //# Copyright (C) 1999,2000
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 LATTICES_LATTICELOCKER_H
29 #define LATTICES_LATTICELOCKER_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/lattices/Lattices/LatticeBase.h>
35 #include <casacore/tables/Tables/TableLock.h>
36 
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 // <summary>
41 // Class to hold a (user) lock on a lattice.
42 // </summary>
43 
44 // <use visibility=export>
45 
46 // <reviewed reviewer="" date="" tests="tTableLockSync.cc">
47 // </reviewed>
48 
49 // <prerequisite>
50 //# Classes you should understand before using this one.
51 // <li> <linkto class=Lattice>Lattice</linkto>
52 // <li> <linkto class=TableLock>TableLock</linkto>
53 // </prerequisite>
54 
55 // <synopsis>
56 // Class LatticeLocker can be used to acquire a (user) lock on a lattice.
57 // The lock can be a read or write lock.
58 // The destructor releases the lock when needed.
59 // <p>
60 // LatticeLocker simply uses the <src>lock</src> and <src>unlock</src>
61 // function of class Lattice.
62 // The advantage of LatticeLocker over these functions is that the
63 // destructor of LatticeLocker is called automatically by the system,
64 // so unlocking the lattice does not need to be done explicitly and
65 // cannot be forgotten. Especially in case of exception handling this
66 // can be quite an adavantage.
67 // <p>
68 // This class is meant to be used with the UserLocking option.
69 // It can, however, also be used with the other locking options.
70 // In case of PermanentLocking(Wait) it won't do anything at all.
71 // In case of AutoLocking it will acquire and release the lock when
72 // needed. However, it is possible that the system releases an
73 // auto lock before the LatticeLocker destructor is called.
74 // <p>
75 // The constructor of LatticeLocker will look if the lattice is
76 // already appropriately locked. If so, it will set a flag to
77 // prevent the destructor from unlocking the lattice. In this way
78 // nested locks can be used. I.e. one can safely use LatticeLocker
79 // in a function without having to be afraid that its destructor
80 // would undo a lock set in a higher function.
81 // <br>Similarly LatticeLocker will remember if a lattice was
82 // already read-locked, when a write-lock is acquired. In such a
83 // case the destructor will try to ensure that the lattice remains
84 // read-locked.
85 // </synopsis>
86 
87 // <example>
88 // <srcblock>
89 // // Open a lattice to be updated.
90 // PagedArray<Float> myLattice (Table ("theLattice",
91 // LatticeLock::UserLocking,
92 // Lattice::Update);
93 // // Start of some critical section requiring a lock.
94 // {
95 // LatticeLocker lock1 (myLattice, FileLocker::Write);
96 // ... write the data
97 // }
98 // // The LatticeLocker destructor invoked by } unlocks the table.
99 // </srcblock>
100 // </example>
101 
102 // <motivation>
103 // LatticeLocker makes it easier to unlock a lattice.
104 // It also makes it easier to use locking in a nested way.
105 // </motivation>
106 
107 //# <todo asof="$DATE:$">
108 //# A List of bugs, limitations, extensions or planned refinements.
109 //# </todo>
110 
111 
113 {
114 public:
115  // The constructor acquires a read or write lock on a lattice.
116  // If the lattice was already locked, the destructor will
117  // not unlock the lattice. This means that the class can be used in
118  // a nested way.
119  // <br>
120  // The number of attempts (default = forever) can be specified when
121  // acquiring the lock does not succeed immediately. When nattempts>1,
122  // the system waits 1 second between each attempt, so nattempts
123  // is more or less equal to a wait period in seconds.
124  // An exception is thrown when the lock cannot be acquired.
125  explicit LatticeLocker (LatticeBase& lattice,
127  uInt nattempts = 0);
128 
129  // If the constructor acquired the lock, the destructor releases
130  // the lock and flushes the data if changed.
132 
133  // Has this process the read or write lock, thus can the table
134  // be read or written safely?
136 
137 private:
138  // The copy constructor and assignment are not possible.
139  // Note that only one lock can be held on a lattice, so copying a
140  // TableLocker object imposes great difficulties which object should
141  // release the lock.
142  // It can be solved by turning LatticeLocker into a handle class
143  // with a reference counted body class.
144  // However, that will only be done when the need arises.
145  // <group>
148  // </group>
149 
150  //# Variables.
154 };
155 
156 
158 {
159  return itsLatticePtr->hasLock (type);
160 }
161 
162 
163 
164 } //# NAMESPACE CASACORE - END
165 
166 #endif
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual Bool hasLock(FileLocker::LockType) const
~LatticeLocker()
If the constructor acquired the lock, the destructor releases the lock and flushes the data if change...
LatticeLocker(LatticeBase &lattice, FileLocker::LockType, uInt nattempts=0)
The constructor acquires a read or write lock on a lattice.
LatticeLocker(const LatticeLocker &)
The copy constructor and assignment are not possible.
LatticeBase * itsLatticePtr
Bool hasLock(FileLocker::LockType) const
Has this process the read or write lock, thus can the table be read or written safely?
LatticeLocker & operator=(const LatticeLocker &)
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