NAME

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

SYNOPSIS

   use Mail::Box;
   use Mail::Box::Locker;
   my $locker = new Mail::Box::Locker(folder => $folder);

   $locker->lock;
   $locker->isLocked;
   $locker->hasLock;
   $locker->unlock;

   my $folder = new Mail::Box(lock_method => 'DOTLOCK');
   print $folder->lockMethod;
   $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 mail-folders.

Each Mail::Box-folder will create its own Mail::Box::Locker object, which will handle the locking for it. You can access of the object directly from the folder, as shown in the examples below. Sometimes the names of the methods had to be changed to avoid confusion.

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 | OBJECT

  Which METHOD has to be used for locking. Supported are

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

  Disable locking.

  The other option (but this is implemented in Mail::Box) is to produce your own Mail::Box::Locker derived class, which implements the desired locking method [you may consider to offer 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(lock_method => $locker);

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

• lock_file => FILENAME

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

name

Return the way this folder was locked. It can only be set as option to the creation of a folder. The method-name is returned in uppercase. You can also get the name of the locking method via the lockMethod call of a Mail::Box folder.

Examples:

    if($locker->name eq 'FILE') ...
    if($folder->lockMethod eq 'FILE') ...

Basic functions

lock FOLDER

Get a lock on a folder. This will return false if the lock fails.

Examples:

    die unless $locker->lock;
    if($folder->lock) {...}

isLocked

Test if the folder is locked by this or a different application.

Examples:

    if($locker->isLocked) {...}
    if($folder->isLocked) {...}

hasLock

Check whether the folder has the lock.

Examples:

    if($locker->hasLock) {...}
    if($folder->hasLock) {...}

unlock

Undo the lock on a folder.

Examples:

    $locker->unlock;
    $folder->unlock;

filename

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

Examples:

   print $locker->filename;
   print $folder->lockFilename;

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.200