1LockedFile(3)         User Contributed Perl Documentation        LockedFile(3)
2
3
4

NAME

6       IO::LockedFile Class - supply object methods for locking files
7

SYNOPSIS

9         use IO::LockedFile;
10
11         # 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
16         # when we close the file - it become unlocked.
17         $file->close();
18
19         # 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

DESCRIPTION

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
29       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
33       So, if you are just interested in having locked files with "flock", you
34       can skip most of the documentation below.
35
36       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
40       Actually the class IO::LockedFile is kind of abstract class.
41
42       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
47       Why "kind" of abstract? Because the constructor of this class will
48       return an object!
49
50       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
54       So by default the constructor of IO::LockedFile will return an object
55       of IO::LockedFile::Flock. For example, the following:
56
57          use IO::LockedFile;
58          $lock = new IO::LockedFile(">bla");
59          print ref($lock);
60
61       Will give:
62
63          IO::LockedFile::Flock
64
65       So what are the conclusions here?
66
67       First of all - do not be surprised to get object of derived class from
68       the constructor of IO::LockedFile.
69
70       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
74       The default behavior of the constructor is determined by the global
75       options.
76
77       We can access this global options, or the options per object using the
78       method "set_option" and "get_option".
79
80       We can set the global options in the use line:
81
82         use IO::LockedFile 'Flock'; # set the default scheme to be Flock
83
84         use IO::LockedFile ( scheme => Flock );
85
86       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
90       Which options are available?
91
92       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
97       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
106       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
117       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
121       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
125       The classes that currently implement the interface that IO::LockedFile
126       defines are:
127
128IO::LockedFile::Flock
129

CONSTRUCTOR

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
138       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

METHODS

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
163       close ( )
164           The file will be closed and unlocked. The method returns the same
165           as the close method of IO::File.
166
167       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
181       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
188       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
195       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
201       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
207       is_writable ( )
208           This method will return 1 (true) if the file was opened to write.
209           Will return 0 (false) otherwise.
210
211       should_block ( )
212           This method will return 1 (true) if the block option set to 1.
213           Will return 0 (false) otherwise.
214
215       should_lock ( )
216           This method will return 1 (true) if the lock option set to 1.  Will
217           return 0 (false) otherwise.
218
219       get_scheme ( )
220           This method will return the name of the scheme that is currently
221           used.
222

AUTHORS

224       Rani Pinchuk, rani@cpan.org
225
226       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

SEE ALSO

234       IO::File(3), IO::LockedFile::Flock(3)
235
236
237
238perl v5.32.1                      2021-01-27                     LockedFile(3)
Impressum