Box::Locker(3)

NAME
Mail::Box::Locker - manage the locking of mail folders

CLASS HIERARCHY
 Mail::Box::Locker
 is a Mail::Reporter

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

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

 use Mail::Box;
 my $folder = Mail::Box->new(lock_method => 'DOTLOCK');
 print $folder->locker->type;

DESCRIPTION
Read Mail::Box-Overview first. The locker module provides the locking functionality needed when handling mail-folders.

Each "Mail::Box" 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.

METHOD INDEX
Methods prefixed with an abbreviation are described in Mail::Reporter (MR).

The general methods for "Mail::Box::Locker" objects:

      DESTROY                              name
   MR errors                               new OPTIONS
      filename                          MR report [LEVEL]
      hasLock                           MR reportAll [LEVEL]
      isLocked                          MR trace [LEVEL]
      lock FOLDER                          unlock
   MR log [LEVEL [,STRINGS]]            MR warnings

The extra methods for extension writers:

   MR AUTOLOAD                          MR logPriority LEVEL
   MR DESTROY                           MR logSettings
   MR inGlobalDestruction               MR notImplemented

METHODS

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

    Generally the client program specifies the locking behavior through options given to the folder class.

     OPTIONS        DESCRIBED IN               DEFAULT
     file           Mail::Box::Locker          undef
     folder         Mail::Box::Locker          <obligatory>
     log            Mail::Reporter             'WARNINGS'
     method         Mail::Box::Locker          'DOTLOCK'
     expires        Mail::Box::Locker          1 hour
     trace          Mail::Reporter             'WARNINGS'
     timeout        Mail::Box::Locker          10 seconds

    * method => METHOD | CLASS
        Which kind of locking, specified as one of the following names, or a full CLASS name. Supported METHODs are

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

            On various folder types, the lockfile differs. See the documentation for each folder, which describes the locking strategy as well as special options to change the default behavior.

        'FLOCK' | 'flock'
            For some folder handlers, locking is based on a file locking mechanism provided by the operating system. However, this does not work on all systems, such as network filesystems, and such. This also doesn't work on folders based on directories ("Mail::Box::MH" and derived).

        'POSIX' | 'posix'
            Use the POSIX standard fcntl locking.

        'MULTI' | 'multi'
            Try more than one locking method to be used at the same time, probably all available, to avoid any chance that you miss a lock from a different application.

        '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'
            Do not use locking.

        The other option is to produce your own "Mail::Box::Locker" derived class, which implements the desired locking method. (Please consider offering 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);

    * expires => SECONDS
        How long can a lock exist? If a different e-mail program leaves a stale lock, then this lock will be removed automatically after the specified number of seconds.

    * folder => FOLDER
        Which folder is locked.

    * timeout => SECONDS|'NOTIMEOUT'
        How long to wait while trying to acquire the lock. The lock request will fail when the specified number of seconds is reached. If 'NOTIMEOUT' is specified, the module will wait until the lock can be taken.

        Whether it is possible to limit the wait time is platform- and locking-method-specific. For instance, the `dotlock' method on Windows will always wait until the lock has been received.

    * file => FILENAME
        Name of the file to lock, or the name of the lockfile (depends on the kind of lock used).

name
    Returns the method used to lock the folder. See the "new" method for details on how to specify the lock method. The name of the method is returned in uppercase. You can also get the name of the locking method via the "lockMethod" call of a "Mail::Box" folder.

    Example:

        if($locker->name eq 'FLOCK') ...

METHODS

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->locker->hasLock) {...}

unlock
    Undo the lock on a folder.

    Examples:

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

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

    Examples:

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

DESTROY
    When the locker is destroyed, for instance when the folder is closed or the program ends, the lock will be automatically removed.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@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 2.018.

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