Mail::Box::Locker(3pm)					User Contributed Perl Documentation				    Mail::Box::Locker(3pm)

NAME

       Mail::Box::Locker - manage the locking of mail folders

INHERITANCE

	Mail::Box::Locker
	  is a Mail::Reporter

	Mail::Box::Locker is extended by
	  Mail::Box::Locker::DotLock
	  Mail::Box::Locker::FcntlLock
	  Mail::Box::Locker::Flock
	  Mail::Box::Locker::Multi
	  Mail::Box::Locker::Mutt
	  Mail::Box::Locker::NFS
	  Mail::Box::Locker::POSIX

SYNOPSIS

	use Mail::Box::Locker;
	my $locker = new Mail::Box::Locker(folder => $folder);

	$locker->lock;
	$locker->isLocked;
	$locker->hasLock;
	$locker->unlock;

	use Mail::Box;
	my $folder = Mail::Box->new(lock_method => 'DOTLOCK');
	print $folder->locker->type;

DESCRIPTION

       Each Mail::Box will create its own "Mail::Box::Locker" object which will handle the locking for it.  You can access of the object directly
       from the folder, as shown in the examples below.

METHODS

   Constructors
       Mail::Box::Locker->new(OPTIONS)
	   Create a new lock. You may do this directly. However, in most cases the lock will not be separately instantiated but will be the second
	   class in a multiple inheritance construction with a Mail::Box.

	   Generally the client program specifies the locking behavior through options given to the folder class.

	    -Option --Defined in     --Default
	     expires		       1 hour
	     file		       undef
	     folder		       <undef>
	     log      Mail::Reporter   'WARNINGS'
	     method		       'DOTLOCK'
	     timeout		       10 seconds
	     trace    Mail::Reporter   'WARNINGS'

	   expires => SECONDS
	     How long can a lock exist?  If a different e-mail program leaves a stale lock, then this lock will be removed automatically after the
	     specified number of seconds.

	   file => FILENAME
	     Name of the file to lock.	By default, the name of the folder is taken.

	   folder => FOLDER
	     Which FOLDER is to be locked, a Mail::Box object.

	   log => LEVEL
	   method => STRING|CLASS|ARRAY
	     Which kind of locking, specified as one of the following names as STRING.	You may also specify a CLASS name, or an ARRAY of names.
	     In case of an ARRAY, a 'multi' locker is started with all thee full CLASS name.

	     Supported locking names are

	     'DOTLOCK' | 'dotlock'
		 The folder handler creates a file which signals that it is in use.  This is a bit problematic, because not all mail-handling
		 software agree on the name of the file to be created.

		 On various folder types, the lockfile differs.  See the documentation for each folder, which describes the locking strategy as
		 well as special options to change the default behavior.

	     'FLOCK' | 'flock'
		 For some folder handlers, locking is based on a file locking mechanism provided by the operating system.  However, this does not
		 work on all systems, such as network filesystems, and such. This also doesn't work on folders based on directories
		 (Mail::Box::Dir and derived).

	     'FCNTLLOCK' | 'fcntllock'
		 POSIX locking via File::FcntlLock, which works on more platforms.  However, that module requires a C compiler to install.

	     'POSIX' | 'posix'
		 Use the POSIX standard fcntl locking.

	     'MULTI' | 'multi'
		 Use ALL available locking methods at the same time, to have a bigger chance that the folder will not be modified by some other
		 application which uses an unspecified locking method.	When one of the locking methods disallows access, the locking fails.

	     'MUTT'| 'mutt'
		 Use the external program 'mutt_dotlock' to lock and unlock.

	     'NFS' | 'nfs'
		 A kind of "dotlock" file-locking mechanism, but adapted to work over NFS.  Extra precaution is needed because an "open O_EXCL" on
		 NFS is not an atomic action.

	     'NONE' | 'none'
		 Do not use locking.

	     The other option is to produce your own "Mail::Box::Locker" derived class, which implements the desired locking method. (Please
	     consider offering it for inclusion in the public Mail::Box module!) Create an instance of that class with this parameter:

	      my $locker = Mail::Box::Locker::MyOwn->new;
	      $folder->open(locker => $locker);

	   timeout => SECONDS|'NOTIMEOUT'
	     How long to wait while trying to acquire the lock. The lock request will fail when the specified number of seconds is reached.  If
	     'NOTIMEOUT' is specified, the module will wait until the lock can be taken.

	     Whether it is possible to limit the wait time is platform- and locking-method-specific.  For instance, the `dotlock' method on
	     Windows will always wait until the lock has been received.

	   trace => LEVEL

   The Locker
       $obj->filename([FILENAME])
	   Returns the filename which is used to lock the folder, optionally after setting it to the specified FILENAME.

	   example:

	    print $locker->filename;

       $obj->folder([FOLDER])
	   Returns the folder object which is locker.

       $obj->name()
	   Returns the method used to lock the folder. See the new(method) for details on how to specify the lock method.  The name of the method
	   is returned in upper-case.

	   example:

	    if($locker->name eq 'FLOCK') ...

   Locking
       $obj->hasLock()
	   Check whether the folder has the lock.

	   example:

	    if($locker->hasLock) {...}
	    if($folder->locker->hasLock) {...}

       $obj->isLocked()
	   Test if the folder is locked by this or a different application.

	   example:

	    if($locker->isLocked) {...}
	    if($folder->locker->isLocked) {...}

       $obj->lock(FOLDER)
	   Get a lock on a folder.  This will return false if the lock fails.

	   example:

	    die unless $locker->lock;
	    if($folder->locker->lock) {...}

       $obj->unlock()
	   Undo the lock on a folder.

	   example:

	    $locker->unlock;
	    $folder->locker->unlock;

   Error handling
       $obj->AUTOLOAD()
	   See "Error handling" in Mail::Reporter

       $obj->addReport(OBJECT)
	   See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
       Mail::Box::Locker->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
	   See "Error handling" in Mail::Reporter

       $obj->errors()
	   See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])
       Mail::Box::Locker->log([LEVEL [,STRINGS]])
	   See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Box::Locker->logPriority(LEVEL)
	   See "Error handling" in Mail::Reporter

       $obj->logSettings()
	   See "Error handling" in Mail::Reporter

       $obj->notImplemented()
	   See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])
	   See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])
	   See "Error handling" in Mail::Reporter

       $obj->trace([LEVEL])
	   See "Error handling" in Mail::Reporter

       $obj->warnings()
	   See "Error handling" in Mail::Reporter

   Cleanup
       $obj->DESTROY()
	   When the locker is destroyed, for instance when the folder is closed or the program ends, the lock will be automatically removed.

       $obj->inGlobalDestruction()
	   See "Cleanup" in Mail::Reporter

DIAGNOSTICS

       Error: Package $package does not implement $method.
	   Fatal error: the specific package (or one of its superclasses) does not implement this method where it should. This message means that
	   some other related classes do implement this method however the class at hand does not.  Probably you should investigate this and
	   probably inform the author of the package.

SEE ALSO

       This module is part of Mail-Box distribution version 2.105, built on May 07, 2012. Website: http://perl.overmeer.net/mailbox/

LICENSE

       Copyrights 2001-2012 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.14.2							    2012-05-07						    Mail::Box::Locker(3pm)