NAME

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

SYNOPSIS

use Mail::Box::Locker;
my $locker = new Mail::Box::Locker;

$locker->lock($folder);
$locker->isLocked($folder);
$locker->hasLock($folder);
$locker->unlock($folder);

Mail::Box::Locker->addLockingMethod(...);

# Because Mail::Box inherits from this class:
my $folder = new Mail::Box(lock_method => 'dotlock');
$folder->lock;
$folder->isLocked;
$folder->hasLock;
$folder->unlock;

DESCRIPTION

Read Mail::Box::Manager first. The locker module contains the various locking functionalities as needed when handling folders.

Because Mail::Box inherits from Mail::Box::Locker, this example works:

my $folder
$folder->lock;

PUBLIC INTERFACE

new ARGS

Create a new lock. You may do this, however, in most cases the lock will not be seperately instantiated but be the second class in a multiple inheritance construction with a Mail::Box.

ARGS is a reference to a hash, where the following fields are used for the locker information:

lock_method => METHOD

Which method has to be used for locking. Supported are

• 'dotlock'

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

  On various folder-types, the lockfile differs. See each manual-page and special options to change their default behavior.

• 'file'

  For some folder handlers, locking is based on simply file-locking mechanism. However, this does not work on network filesystems, and such. This also doesn't work on directory-type of folders (Mail::Box::Dir and derived).

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

  Disable locking.

lock_timeout => SECONDS

How long can a lock stand? When an different e-mail program left a lock, then this will be removed automatically after the specified seconds. The default is one hour.

lock_wait => SECONDS

How long to wait for receiving the lock. The lock-request may fail. If SECONDS equals 'NOTIMEOUT', then we wait till the lock can be taken.

lockfile => FILENAME

Name of the file to take the lock on or to represent a lock (depends on the kind of lock used).

lockingMethod NAME, CODE, CODE, CODE

(class method) Add locking methods to the set of know methods. You need to specify a method-name and three code references, respectively for the get, test, and un method. You may also specify method-names instead of code-references.

Basic functions

The lock, test_lock, and unlock methods are to be used. They call specific methods which implement the right locking mechanism. Do not call the various locking methods directly.

lock [FOLDER] [METHOD]

Get a lock on a folder, by using the predefined method, or a specific METHOD. If you do not specify a FOLDER, it is assumed the locking functionality is inherited.

Examples: $locker->lock($folder); $folder->lock;

isLocked [FOLDER] [METHOD]

Test if the folder is locked.

Examples: $locker->isLocked($folder); $folder->isLocked;

hasLock [FOLDER]

Check wheter the folder has the lock.

Examples: $locker->hasLock($folder); $folder->hasLock;

unlock [FOLDER] [METHOD]

un the lock on a folder.

Examples: $locker->unlock($folder); $folder->unlock;

lockFilename [FILENAME]

Returns the filename which is used to lock the folder. It depends on the locking method how this file is used.

AUTHOR

Mark Overmeer (Mark@Overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is alpha, version 0.4