Mail::Box::Locker - manage the locking of mail folders |
Mail::Box::Locker - manage the locking of mail folders
Mail::Box::Locker is a Mail::Reporter
Mail::Box::Locker is extended by Mail::Box::Locker::DotLock Mail::Box::Locker::Flock Mail::Box::Locker::Multi Mail::Box::Locker::NFS Mail::Box::Locker::POSIX
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;
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.
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 <required> log L<Mail::Reporter> C<'WARNINGS'> method C<'DOTLOCK'> timeout 10 seconds trace L<Mail::Reporter> C<'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
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.
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.
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
$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
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') ...
$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;
$obj->AUTOLOAD
See Error handling in the Mail::Reporter manpage
$obj->addReport(OBJECT)
See Error handling in the Mail::Reporter manpage
$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Box::Locker->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
See Error handling in the Mail::Reporter manpage
$obj->errors
See Error handling in the Mail::Reporter manpage
$obj->log([LEVEL [,STRINGS]])
Mail::Box::Locker->log([LEVEL [,STRINGS]])
See Error handling in the Mail::Reporter manpage
$obj->logPriority(LEVEL)
Mail::Box::Locker->logPriority(LEVEL)
See Error handling in the Mail::Reporter manpage
$obj->logSettings
See Error handling in the Mail::Reporter manpage
$obj->notImplemented
See Error handling in the Mail::Reporter manpage
$obj->report([LEVEL])
See Error handling in the Mail::Reporter manpage
$obj->reportAll([LEVEL])
See Error handling in the Mail::Reporter manpage
$obj->trace([LEVEL])
See Error handling in the Mail::Reporter manpage
$obj->warnings
See Error handling in the Mail::Reporter manpage
$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 the Mail::Reporter manpage
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 the MailBox website at http://perl.overmeer.net/mailbox/ for more details.
Distribution version 2.059. Written by Mark Overmeer (mark@overmeer.net) See the ChangeLog for other contributors.
Copyright (c) 2001-2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Mail::Box::Locker - manage the locking of mail folders |