/ 
Mail-Box-0.94
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::Locker

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;

METHOD

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 beta, version 0.94