1LockedFile(3) User Contributed Perl Documentation LockedFile(3)
2
6 IO::LockedFile Class - supply object methods for locking files
7
9 use IO::LockedFile;
10 # create new locked file object. $file will hold a file handle.
12 # if the file is already locked, the method will not return until the
13 # file is unlocked
14 my $file = new IO::LockedFile(">locked1.txt");
15 # when we close the file - it become unlocked.
17 $file->close();
18 # suppose we did not have the line above, we can also delete the
20 # object, and the file is automatically unlocked and closed.
21 $file = undef;
22
24 In its simplistic use, the IO::LockedFile class gives us the same
25 interface of the IO::File class with the unique difference that the
26 files we deal with are locked using the Flock mechanism (using the
27 "flock" function).
28 If during the running of the process, it crashed - the file will be
30 automatically unlocked. Actually - if the IO::LockedFile object goes
31 out of scope, the file is automatically closed and unlocked.
32 So, if you are just interested in having locked files with "flock", you
34 can skip most of the documentation below.
35 If, on the other hand, you are interested in locking files with other
37 schemes then Flock, or you want to control the behavior of the locking
38 (having non blocking lock for example), read on.
39 Actually the class IO::LockedFile is kind of abstract class.
41 Why abstract? Because methods of this class call the methods "lock" and
43 "unlock". But those methods are not really implemented in this class.
44 They suppose to be implemented in the derived classes of
45 IO::LockedFile.
46 Why "kind" of abstract? Because the constructor of this class will
48 return an object!
49 How abstract class can create objects? This is done by having the
51 constructor returning object that is actually an object of one of the
52 derived classes of IO::LockedFile.
53 So by default the constructor of IO::LockedFile will return an object
55 of IO::LockedFile::Flock. For example, the following:
56 use IO::LockedFile;
58 $lock = new IO::LockedFile(">bla");
59 print ref($lock);
60 Will give:
62 IO::LockedFile::Flock
64 So what are the conclusions here?
66 First of all - do not be surprised to get object of derived class from
68 the constructor of IO::LockedFile.
69 Secondly - by changing the default behavior of the constructor of
71 IO::LockedFile, we can get object of other class which means that we
72 have a locked file that is locked with other scheme.
73 The default behavior of the constructor is determined by the global
75 options.
76 We can access this global options, or the options per object using the
78 method "set_option" and "get_option".
79 We can set the global options in the use line:
81 use IO::LockedFile 'Flock'; # set the default scheme to be Flock
83 use IO::LockedFile ( scheme => Flock );
85 We can also set the options of a new object by passing the options to
87 the constructor, as we will see below. We can change the options of an
88 existing object by using the "set_option" method.
89 Which options are available?
91 scheme
93 The scheme let us define which derived class we use for the object
94 we create. See below which derived classes are available. The
95 default scheme is 'Flock'.
96 block
98 The block option can be 1 or 0 (true or false). If it is 1, a call
99 to the "open" method or to the constructor will be blocked if the
100 file we try to open is already locked. This means that those
101 methods will not return till the file is unlocked. If the value of
102 the block option is 0, the "open" and the constructor will return
103 immediately in any case. If the file is locked, those methods will
104 return undef. The default value of the block option is 1.
105 lock
107 The lock option can be 1 or 0 (true or false). It defines if the
108 file we open when we create the object will be opened locked.
109 Sometimes, we want to have a file that can be locked, yet we do not
110 want to open it locked from the beginning. For example if we want
111 to print into a log file, usually we want to lock that file only
112 when we print into it. Yet, it might be that when we open the file
113 in the beginning we do not print into it immediately. In that case
114 we will prefer to open the file as unlocked, and later we will lock
115 it when needed. The default value of the lock option is 1.
116 There might be extra options that are used by one of the derived
118 classes. So according to the scheme you choose to use, please look in
119 the manual page of the class that implement that scheme.
120 Finally, some information that is connected to a certain scheme will be
122 found in the classes that are derived from this class. For example,
123 compatibility issues will be discussed in each derived classes.
124 The classes that currently implement the interface that IO::LockedFile
126 defines are:
127 ยท IO::LockedFile::Flock
129
131 new ( FILENAME [,MODE [,PERMS]] )
132 Creates an object that belong to one of the derived classes of
133 "IO::LockedFile". If it receives any parameters, they are passed to
134 the method "open". if the "open" fails, the object is destroyed.
135 Otherwise, it is returned to the caller. The object will be the
136 file handle of that opened file.
137 new ( OPTIONS, FILENAME [,MODE [,PERMS]] )
139 This version of the constructor is the same as above, with the
140 difference that we send as the first parameter a reference to a
141 hash - OPTIONS. This hash let us change for this object only, the
142 options from the default options. So for example if we want to
143 change the lock option from its default we can do it as follow:
144 $file = new IO::LockedFile( { lock => 0 },
145 ">locked_later.txt" );
146
148 open ( FILENAME [,MODE [,PERMS]] )
149 The method let us open the file FILENAME. By default, the file will
150 be opened as a locked file, and if the file that is opened is
151 already locked, the method will not return until the file is
152 unlocked. Of course this default behavior can be controlled by
153 setting other options. The object will be the file handle of that
154 opened file. The parameters that should be provided to this method
155 are the same as the parameters that the method "open" of IO::File
156 accepts. (like ">file.txt" for example). Note that the open method
157 checks if the file is opened for reading or for writing, and only
158 then calls the lock method of the derived class that is being used.
159 This way, for example, when using the Flock scheme, the lock will
160 be a shared lock for a file that is being read, and exclusive lock
161 for a file that is opened to be write.
162 close ( )
164 The file will be closed and unlocked. The method returns the same
165 as the close method of IO::File.
166 lock ( )
168 Practically this method does nothing, and returns 1 (true). This
169 method will be overridden by the derived class that implements the
170 scheme we use. When it is overridden, the method suppose to lock
171 the file according to the scheme we use. If the file is already
172 locked, and the block option is 1 (true), the method will not
173 return until the file is unlocked, and locked again by the method.
174 If the block option is 0 (false), the method will return 0
175 immediately. Besides, the lock method is aware if the file was
176 opened for reading or for writing. Thus, for example, when using
177 the Flock scheme, the method will create a shared lock for a file
178 that is being read, and exclusive lock for a file that is opened to
179 be write.
180 unlock ( )
182 Practically this method does nothing, and returns 1 (true). This
183 method will be overridden by the derived class that implements the
184 scheme we use. When it is overridden, the method suppose to unlock
185 the file according to the scheme we use, and return 1 (true) on
186 success and 0 (false) on failure.
187 have_lock ( )
189 Will return 1 (true) if the file is already locked by this object.
190 Will return 0 (false) otherwise. Note that this will not tell us
191 anything about the situation of the file itself - thus we should
192 not use this method in order to check if the file is locked by
193 someone else.
194 print ( )
196 This method is exactly like the "print" method of IO::Handle, with
197 the difference that when using this method, if the file is
198 unlocked, then before printing to it, it will be locked and
199 afterward it will be unlocked.
200 truncate ( )
202 This method is exactly like the "truncate" method of IO::Handle,
203 with the difference that when using this method, if the file is
204 unlocked, then before truncating it, it will be locked and
205 afterward it will be unlocked.
206 is_writable ( )
208 This method will return 1 (true) if the file was opened to write.
209 Will return 0 (false) otherwise.
210 should_block ( )
212 This method will return 1 (true) if the block option set to 1.
213 Will return 0 (false) otherwise.
214 should_lock ( )
216 This method will return 1 (true) if the lock option set to 1. Will
217 return 0 (false) otherwise.
218 get_scheme ( )
220 This method will return the name of the scheme that is currently
221 used.
222
224 Rani Pinchuk, rani@cpan.org
225 Rob Napier, rnapier@employees.org
227
229 Copyright (c) 2001-2002 Ockham Technology N.V. & Rani Pinchuk. All
230 rights reserved. This package is free software; you can redistribute
231 it and/or modify it under the same terms as Perl itself.
232
234 IO::File(3), IO::LockedFile::Flock(3)
235perl v5.12.0 2003-02-20 LockedFile(3)