22

✏️ Editing: IO::LockedFile.3pm

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "LockedFile 3"
.TH LockedFile 3 "2003-02-20" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::LockedFile Class \- supply object methods for locking files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In its simplistic use, the \fBIO::LockedFile\fR class gives us the same 
interface of the \fBIO::File\fR class with the unique difference that the 
files we deal with are locked using the \fBFlock\fR mechanism (using the 
\&\f(CW\*(C`flock\*(C'\fR function).
.PP
If during the running of the process, it crashed \- the file will 
be automatically unlocked. Actually \- if the \fBIO::LockedFile\fR object goes
out of scope, the file is automatically closed and unlocked.
.PP
So, if you are just interested in having locked files with \f(CW\*(C`flock\*(C'\fR, you 
can skip most of the documentation below.
.PP
If, on the other hand, you are interested in locking files with other
schemes then \fBFlock\fR, or you want to control the behavior of the locking
(having non blocking lock for example), read on.
.PP
Actually the class \fBIO::LockedFile\fR is kind of abstract class.
.PP
Why abstract? Because methods of this class call the methods \f(CW\*(C`lock\*(C'\fR
and \f(CW\*(C`unlock\*(C'\fR. But those methods are not really implemented in this class. 
They suppose to be implemented in the derived classes of \fBIO::LockedFile\fR.
.PP
Why \*(L"kind\*(R" of abstract? Because the constructor of this class will return an
object!
.PP
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
\&\fBIO::LockedFile\fR.
.PP
So by default the constructor of \fBIO::LockedFile\fR will return an object of
\&\fBIO::LockedFile::Flock\fR. For example, the following:
.PP
.Vb 3
\&   use IO::LockedFile;
\&   $lock = new IO::LockedFile(">bla");
\&   print ref($lock);
.Ve
.PP
Will give:
.PP
.Vb 1
\&   IO::LockedFile::Flock
.Ve
.PP
So what are the conclusions here?
.PP
First of all \- do not be surprised to get object of derived class from the
constructor of \fBIO::LockedFile\fR.
.PP
Secondly \- by changing the default behavior of the constructor of
\&\fBIO::LockedFile\fR, we can get object of other class which means that we
have a locked file that is locked with other scheme.
.PP
The default behavior of the constructor is determined by the global options.
.PP
We can access this global options, or the options per object using the method
\&\f(CW\*(C`set_option\*(C'\fR and \f(CW\*(C`get_option\*(C'\fR.
.PP
We can set the global options in the use line:
.PP
.Vb 1
\&  use IO::LockedFile \*(AqFlock\*(Aq; # set the default scheme to be Flock
\&
\&  use IO::LockedFile ( scheme => Flock );
.Ve
.PP
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 \f(CW\*(C`set_option\*(C'\fR method.
.PP
Which options are available?
.IP "\fIscheme\fR" 4
.IX Item "scheme"
The \fIscheme\fR 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'.
.IP "\fIblock\fR" 4
.IX Item "block"
The \fIblock\fR option can be 1 or 0 (true or false). If it is 1, a call to the
\&\f(CW\*(C`open\*(C'\fR 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 \fIblock\fR option is 0, the \f(CW\*(C`open\*(C'\fR and the
constructor will return immediately in any case. If the file is locked,
those methods will return undef. The default value of the \fIblock\fR option is
1.
.IP "\fIlock\fR" 4
.IX Item "lock"
The \fIlock\fR 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 \fIlock\fR option is 1.
.PP
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.
.PP
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.
.PP
The classes that currently implement the interface that \fBIO::LockedFile\fR
defines are:
.IP "\(bu" 4
\&\fBIO::LockedFile::Flock\fR
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( \s-1FILENAME\s0 [,MODE [,PERMS]] )" 4
.IX Item "new ( FILENAME [,MODE [,PERMS]] )"
Creates an object that belong to one of the derived classes of 
\&\f(CW\*(C`IO::LockedFile\*(C'\fR. If it receives any parameters, they are passed 
to the method \f(CW\*(C`open\*(C'\fR. if the \f(CW\*(C`open\*(C'\fR fails, the object is destroyed. 
Otherwise, it is returned to the caller. The object will be 
the file handle of that opened file.
.IP "new ( \s-1OPTIONS, FILENAME\s0 [,MODE [,PERMS]] )" 4
.IX Item "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 \- \s-1OPTIONS.\s0 This
hash let us change for this object only, the options from the default 
options. So for example if we want to change the \fIlock\fR option from its 
default we can do it as follow:
  \f(CW$file\fR = new IO::LockedFile( { lock => 0 }, 
                              \*(L">locked_later.txt\*(R" );
.SH "METHODS"
.IX Header "METHODS"
.IP "open ( \s-1FILENAME\s0 [,MODE [,PERMS]] )" 4
.IX Item "open ( FILENAME [,MODE [,PERMS]] )"
The method let us open the file \s-1FILENAME.\s0 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 \f(CW\*(C`open\*(C'\fR of  
\&\fBIO::File\fR accepts. (like \*(L">file.txt\*(R" 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 \fBFlock\fR 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.
.IP "close ( )" 4
.IX Item "close ( )"
The file will be closed and unlocked. The method returns the same as the 
close method of \fBIO::File\fR.
.IP "lock ( )" 4
.IX Item "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 \fIblock\fR option is 1 
(true), the method will not return until the file is unlocked, and 
locked again by the method. If the \fIblock\fR 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 \fBFlock\fR 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.
.IP "unlock ( )" 4
.IX Item "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.
.IP "have_lock ( )" 4
.IX Item "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.
.IP "print ( )" 4
.IX Item "print ( )"
This method is exactly like the \f(CW\*(C`print\*(C'\fR method of \fBIO::Handle\fR, 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.
.IP "truncate ( )" 4
.IX Item "truncate ( )"
This method is exactly like the \f(CW\*(C`truncate\*(C'\fR method of \fBIO::Handle\fR, 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.
.IP "is_writable ( )" 4
.IX Item "is_writable ( )"
This method will return 1 (true) if the file was opened to write. 
Will return 0 (false) otherwise.
.IP "should_block ( )" 4
.IX Item "should_block ( )"
This method will return 1 (true) if the block option set to 1.  
Will return 0 (false) otherwise.
.IP "should_lock ( )" 4
.IX Item "should_lock ( )"
This method will return 1 (true) if the lock option set to 1.  
Will return 0 (false) otherwise.
.IP "get_scheme ( )" 4
.IX Item "get_scheme ( )"
This method will return the name of the scheme that is currently used.
.SH "AUTHORS"
.IX Header "AUTHORS"
Rani Pinchuk, rani@cpan.org
.PP
Rob Napier, rnapier@employees.org
.SH "COPYRIGHT"
.IX Header "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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBIO::File\fR\|(3),
\&\fBIO::LockedFile::Flock\fR\|(3)

MR SKB