unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Box::Locker(3pm)User Contributed Perl DocumentatioMail::Box::Locker(3pm)



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

INHERITANCE
        Mail::Box::Locker
          is a Mail::Reporter

        Mail::Box::Locker is extended by
          Mail::Box::Locker::DotLock
          Mail::Box::Locker::Flock
          Mail::Box::Locker::Multi
          Mail::Box::Locker::Mutt
          Mail::Box::Locker::NFS
          Mail::Box::Locker::POSIX

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

METHODS
       Constructors

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

            Option --Defined in     --Default
            expires                   1 hour
            file                      undef
            folder                    <required>
            log      Mail::Reporter   'WARNINGS'
            method                    'DOTLOCK'
            timeout                   10 seconds
            trace    Mail::Reporter   'WARNINGS'

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

           . file => FILENAME

               Name of the file to lock.  By default, the name of the folder
               is taken.

           . folder => FOLDER

               Which FOLDER is to be locked, a Mail::Box object.

           . log => LEVEL

           . method => STRING|CLASS|ARRAY

               Which kind of locking, specified as one of the following names
               as STRING.  You may also specify a CLASS name, or an ARRAY of
               names.  In case of an ARRAY, a 'multi' locker is started with
               all thee full CLASS name.

               Supported locking names 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::Dir and derived).

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

               'MULTI' | 'multi'
                   Use ALL available locking methods at the same time, to have
                   a bigger chance that the folder will not be modified by
                   some other application which uses an unspecified locking
                   method.  When one of the locking methods disallows access,
                   the locking fails.

               'MUTT'| 'mutt'
                   Use the external program 'mutt_dotlock' to lock and unlock.

               '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(locker => $locker);

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

           . trace => LEVEL

       The Locker

       $obj->filename([FILENAME])

           Returns the filename which is used to lock the folder, optionally
           after setting it to the specified FILENAME.

           example:

            print $locker->filename;

       $obj->folder

           Returns the folder object which is locker.

       $obj->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 upper-case.

           example:

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

       Locking

       $obj->hasLock

           Check whether the folder has the lock.

           example:

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

       $obj->isLocked

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

           example:

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

       $obj->lock(FOLDER)

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

           example:

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

       $obj->unlock

           Undo the lock on a folder.

           example:

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

       Error handling

       $obj->AUTOLOAD

           See "Error handling" in Mail::Reporter

       $obj->addReport(OBJECT)

           See "Error handling" in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

       Mail::Box::Locker->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
       CALLBACK])

           See "Error handling" in Mail::Reporter

       $obj->errors

           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])

       Mail::Box::Locker->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)

       Mail::Box::Locker->logPriority(LEVEL)

           See "Error handling" in Mail::Reporter

       $obj->logSettings

           See "Error handling" in Mail::Reporter

       $obj->notImplemented

           See "Error handling" in Mail::Reporter

       $obj->report([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->reportAll([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->trace([LEVEL])

           See "Error handling" in Mail::Reporter

       $obj->warnings

           See "Error handling" in Mail::Reporter

       Cleanup

       $obj->DESTROY

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

       $obj->inGlobalDestruction

           See "Cleanup" in Mail::Reporter

DIAGNOSTICS
       Error: Package $package does not implement $method.

           Fatal error: the specific package (or one of its superclasses) does
           not implement this method where it should. This message means that
           some other related classes do implement this method however the
           class at hand does not.  Probably you should investigate this and
           probably inform the author of the package.

SEE ALSO
       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 by Mark Overmeer. For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html



perl v5.10.0                      2008-04-28            Mail::Box::Locker(3pm)