In its simplistic use, the <B>IO::LockedFileB> class gives us the same
interface of the <B>IO::FileB> class with the unique difference that the
files we deal with are locked using the <B>FlockB> mechanism (using the
If during the running of the process, it crashed - the file will
be automatically unlocked. Actually - if the <B>IO::LockedFileB> 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 <B>FlockB>, or you want to control the behavior of the locking
(having non blocking lock for example), read on.
Actually the class <B>IO::LockedFileB> 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 <B>IO::LockedFileB>.
Why kind of abstract? Because the constructor of this class will return an
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
So by default the constructor of <B>IO::LockedFileB> will return an object of
<B>IO::LockedFile::FlockB>. For example, the following:
$lock = new IO::LockedFile(">bla");
So what are the conclusions here?
First of all - do not be surprised to get object of derived class from the
constructor of <B>IO::LockedFileB>.
Secondly - by changing the default behavior of the constructor of
<B>IO::LockedFileB>, 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?
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.
The scheme let us define which derived class we use for the object
See below which derived classes are available. The default scheme is Flock.
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
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.
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 <B>IO::LockedFileB>