NAME¶
IO::LockedFile - supply object methods for locking files
SYNOPSIS¶
use IO::LockedFile;
# create new locked file object. $file will hold a file handle.
# if the file is already locked, the method will not return until the
# file is unlocked
my $file = new IO::LockedFile(">locked1.txt");
# when we close the file - it become unlocked.
$file->close();
# suppose we did not have the line above, we can also delete the
# object, and the file is automatically unlocked and closed.
$file = undef;
DESCRIPTION¶
In its simplistic use, the
IO::LockedFile class gives us the same
interface of the
IO::File class with the unique difference that the
files we deal with are locked using the
Flock mechanism (using the
"flock" function).
If during the running of the process, it crashed - the file will be
automatically unlocked. Actually - if the
IO::LockedFile object goes
out of scope, the file is automatically closed and unlocked.
So, if you are just interested in having locked files with "flock",
you can skip most of the documentation below.
If, on the other hand, you are interested in locking files with other schemes
then
Flock, or you want to control the behavior of the locking (having
non blocking lock for example), read on.
Actually the class
IO::LockedFile is kind of abstract class.
Why abstract? Because methods of this class call the methods "lock"
and "unlock". But those methods are not really implemented in this
class. They suppose to be implemented in the derived classes of
IO::LockedFile.
Why "kind" of abstract? Because the constructor of this class will
return an object!
How abstract class can create objects? This is done by having the constructor
returning object that is actually an object of one of the derived classes of
IO::LockedFile.
So by default the constructor of
IO::LockedFile will return an object of
IO::LockedFile::Flock. For example, the following:
use IO::LockedFile;
$lock = new IO::LockedFile(">bla");
print ref($lock);
Will give:
IO::LockedFile::Flock
So what are the conclusions here?
First of all - do not be surprised to get object of derived class from the
constructor of
IO::LockedFile.
Secondly - by changing the default behavior of the constructor of
IO::LockedFile, we can get object of other class which means that we
have a locked file that is locked with other scheme.
The default behavior of the constructor is determined by the global options.
We can access this global options, or the options per object using the method
"set_option" and "get_option".
We can set the global options in the use line:
use IO::LockedFile 'Flock'; # set the default scheme to be Flock
use IO::LockedFile ( scheme => Flock );
We can also set the options of a new object by passing the options to the
constructor, as we will see below. We can change the options of an existing
object by using the "set_option" method.
Which options are available?
- scheme
- The scheme let us define which derived class we use
for the object we create. See below which derived classes are available.
The default scheme is 'Flock'.
- block
- The block option can be 1 or 0 (true or false). If
it is 1, a call to the "open" method or to the constructor will
be blocked if the file we try to open is already locked. This means that
those methods will not return till the file is unlocked. If the value of
the block option is 0, the "open" and the constructor
will return immediately in any case. If the file is locked, those methods
will return undef. The default value of the block option is 1.
- lock
- The lock option can be 1 or 0 (true or false). It
defines if the file we open when we create the object will be opened
locked. Sometimes, we want to have a file that can be locked, yet we do
not want to open it locked from the beginning. For example if we want to
print into a log file, usually we want to lock that file only when we
print into it. Yet, it might be that when we open the file in the
beginning we do not print into it immediately. In that case we will prefer
to open the file as unlocked, and later we will lock it when needed. The
default value of the lock option is 1.
There might be extra options that are used by one of the derived classes. So
according to the scheme you choose to use, please look in the manual page of
the class that implement that scheme.
Finally, some information that is connected to a certain scheme will be found in
the classes that are derived from this class. For example, compatibility
issues will be discussed in each derived classes.
The classes that currently implement the interface that
IO::LockedFile
defines are:
- •
- IO::LockedFile::Flock
CONSTRUCTOR¶
- new ( FILENAME [,MODE [,PERMS]] )
- Creates an object that belong to one of the derived classes
of "IO::LockedFile". If it receives any parameters, they are
passed to the method "open". if the "open" fails, the
object is destroyed. Otherwise, it is returned to the caller. The object
will be the file handle of that opened file.
- new ( OPTIONS, FILENAME [,MODE [,PERMS]] )
- This version of the constructor is the same as above, with
the difference that we send as the first parameter a reference to a hash -
OPTIONS. This hash let us change for this object only, the options from
the default options. So for example if we want to change the lock
option from its default we can do it as follow:
$file = new IO::LockedFile( { lock => 0 },
">locked_later.txt" );
METHODS¶
- open ( FILENAME [,MODE [,PERMS]] )
- The method let us open the file FILENAME. By default, the
file will be opened as a locked file, and if the file that is opened is
already locked, the method will not return until the file is unlocked. Of
course this default behavior can be controlled by setting other options.
The object will be the file handle of that opened file. The parameters
that should be provided to this method are the same as the parameters that
the method "open" of IO::File accepts. (like
">file.txt" for example). Note that the open method checks if
the file is opened for reading or for writing, and only then calls the
lock method of the derived class that is being used. This way, for
example, when using the Flock scheme, the lock will be a shared
lock for a file that is being read, and exclusive lock for a file that is
opened to be write.
- close ( )
- The file will be closed and unlocked. The method returns
the same as the close method of IO::File.
- lock ( )
- Practically this method does nothing, and returns 1 (true).
This method will be overridden by the derived class that implements the
scheme we use. When it is overridden, the method suppose to lock the file
according to the scheme we use. If the file is already locked, and the
block option is 1 (true), the method will not return until the file
is unlocked, and locked again by the method. If the block option is
0 (false), the method will return 0 immediately. Besides, the lock method
is aware if the file was opened for reading or for writing. Thus, for
example, when using the Flock scheme, the method will create a
shared lock for a file that is being read, and exclusive lock for a file
that is opened to be write.
- unlock ( )
- Practically this method does nothing, and returns 1 (true).
This method will be overridden by the derived class that implements the
scheme we use. When it is overridden, the method suppose to unlock the
file according to the scheme we use, and return 1 (true) on success and 0
(false) on failure.
- have_lock ( )
- Will return 1 (true) if the file is already locked by this
object. Will return 0 (false) otherwise. Note that this will not tell us
anything about the situation of the file itself - thus we should not use
this method in order to check if the file is locked by someone else.
- print ( )
- This method is exactly like the "print" method of
IO::Handle, with the difference that when using this method, if the
file is unlocked, then before printing to it, it will be locked and
afterward it will be unlocked.
- truncate ( )
- This method is exactly like the "truncate" method
of IO::Handle, with the difference that when using this method, if
the file is unlocked, then before truncating it, it will be locked and
afterward it will be unlocked.
- is_writable ( )
- This method will return 1 (true) if the file was opened to
write. Will return 0 (false) otherwise.
- should_block ( )
- This method will return 1 (true) if the block option set to
1. Will return 0 (false) otherwise.
- should_lock ( )
- This method will return 1 (true) if the lock option set to
1. Will return 0 (false) otherwise.
- get_scheme ( )
- This method will return the name of the scheme that is
currently used.
AUTHORS¶
Rani Pinchuk, rani@cpan.org
Rob Napier, rnapier@employees.org
COPYRIGHT¶
Copyright (c) 2001-2002 Ockham Technology N.V. & Rani Pinchuk. All rights
reserved. This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
SEE ALSO¶
IO::File(3),
IO::LockedFile::Flock(3)