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 CWMail::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'>

'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).

'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.

'NFS' | 'nfs'

A kind of CWdotlock file-locking mechanism, but adapted to work over NFS. Extra precaution is needed because an CWopen O_EXCL on NFS is not an atomic action.

'NONE' | 'none'

Do not use locking. The other option is to produce your own CWMail::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 CW'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 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

$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

Error: Package CW$package does not implement CW$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.063. 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.