casacore
FileLocker.h
Go to the documentation of this file.
1 //# FileLocker.h: Class to handle file locking
2 //# Copyright (C) 1997,1998,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 CASA_FILELOCKER_H
29 #define CASA_FILELOCKER_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 class String;
39 
40 
41 // <summary>
42 // Class to handle file locking.
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tLockFile" demos="">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> man page of fcntl
52 // </prerequisite>
53 
54 // <synopsis>
55 // This class handles file locking by means of the fcntl SETLK function.
56 // Locking of files on NFS-mounted file systems works correctly
57 // as long as the NFS lockd and statd deamons are configured correctly.
58 // Otherwise lock requests may be granted incorrectly.
59 // <p>
60 // Acquiring a lock can be done for a read or a write lock.
61 // Multiple locks on a file can exist as long as they are all
62 // read locks. When a write lock is involved, no other lock can exist.
63 // It is possible to acquire a lock in 2 ways:
64 // <ul>
65 // <li>Wait until the lock request is granted; i.e. until the processes
66 // holding a lock on the file release their lock.
67 // <li>Do several attempts; between each attempt it sleeps 1 second.
68 // Note that nattempts=1 means it returns immediately when the
69 // lock request could not be granted.
70 // </ul>
71 // </synopsis>
72 
73 // <example>
74 // <srcblock>
75 // int fd = open ("file.name");
76 // FileLocker lock(fd);
77 // if (lock.acquire()) {
78 // ... do something with the file ...
79 // lock.release();
80 // }else{
81 // cout << lock.lastMessage() << endl;
82 // }
83 // </srcblock>
84 // </example>
85 
86 // <motivation>
87 // Make it possible to lock files in a standard way.
88 // </motivation>
89 
90 
92 {
93 public:
94  // Define the possible lock types.
95  enum LockType {
96  // Acquire a read lock.
98  // Acquire a write lock.
99  Write
100  };
101 
102  // Default constructor creates an invalid fd.
104 
105  // Construct the FileLocker object for the given file descriptor.
106  // This can be used to lock a segment of the given file.
107  // The segment is given by start and length. Length=0 means till the
108  // end of the file.
109  explicit FileLocker (int fd, uInt start=0, uInt length=0);
110 
112 
113  // Acquire a write or read lock.
114  // <src>nattempts</src> defines how often it tries to acquire the lock.
115  // A zero value indicates an infinite number of times (i.e. wait until
116  // the lock is acquired).
117  // A positive value means it waits 1 second between each attempt.
118  Bool acquire (LockType = Write, uInt nattempts = 0);
119 
120  // Release a lock.
121  // The return status indicates if an error occurred.
123 
124  // Test if the file can be locked for read or write.
125  // Optionally the PID of the process holding the lock is returned.
126  // <group>
129  // </group>
130 
131  // Test if the process has a lock for read or write on the file.
132  Bool hasLock (LockType = Write) const;
133 
134  // Get the fd in use.
135  int fd() const;
136 
137  // Get the last error.
138  int lastError() const;
139 
140  // Get the message belonging to the last error.
142 
143 private:
144  int itsFD;
145  int itsError;
146  int itsStart;
151 };
152 
153 
154 inline Bool FileLocker::hasLock (LockType type) const
155 {
156  return (type == Write ? itsWriteLocked : itsReadLocked);
157 }
158 inline int FileLocker::fd() const
159 {
160  return itsFD;
161 }
162 inline int FileLocker::lastError() const
163 {
164  return itsError;
165 }
166 
167 
168 
169 } //# NAMESPACE CASACORE - END
170 
171 #endif
172 
Bool canLock(uInt &pid, LockType=Write)
int lastError() const
Get the last error.
Definition: FileLocker.h:162
Bool itsReadLocked
temporary for SUSE 6.1
Definition: FileLocker.h:149
Bool canLock(LockType=Write)
Test if the file can be locked for read or write.
Bool release()
Release a lock.
int fd() const
Get the fd in use.
Definition: FileLocker.h:158
Bool hasLock(LockType=Write) const
Test if the process has a lock for read or write on the file.
Definition: FileLocker.h:154
LockType
Define the possible lock types.
Definition: FileLocker.h:95
@ Write
Acquire a write lock.
Definition: FileLocker.h:99
@ Read
Acquire a read lock.
Definition: FileLocker.h:97
String lastMessage() const
Get the message belonging to the last error.
Bool acquire(LockType=Write, uInt nattempts=0)
Acquire a write or read lock.
FileLocker(int fd, uInt start=0, uInt length=0)
Construct the FileLocker object for the given file descriptor.
FileLocker()
Default constructor creates an invalid fd.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode length(const LatticeExprNode &expr, const LatticeExprNode &axis)
2-argument function to get the length of an axis.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42