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