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