Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LockedFile(3)	      User Contributed Perl Documentation	 LockedFile(3)

NAME
       IO::LockedFile Class - 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:

       o   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)

perl v5.24.1			  2003-02-20			 LockedFile(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | AUTHORS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::LockedFile&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help