casacore
Loading...
Searching...
No Matches
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
38namespace 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{
114public:
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
137private:
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 & operator=(const LatticeLocker &)
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?
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