Mail::Box::Locker(3) User Contributed Perl Documentation Mail::Box::Locker(3)NAMEMail::Box::Locker - manage the locking of mail folders
INHERITANCEMail::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.094, built on
April 06, 2010. Website: http://perl.overmeer.net/mailbox/
LICENSE
Copyrights 2001-2010 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.10.1 2010-04-06 Mail::Box::Locker(3)
