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

  How long to wait for receiving the lock. The lock-request may fail, when the specified number of seconds is reached. If 'NOTIMEOUT' is specified, we wait till the lock can be taken.

  It is platform and locking method specific whether it is possible at all to limit the trials to the specified number of seconds. For instance, the `dotlock' method on Windows will always wait until the lock has been received.

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