Provided by: libmail-box-perl_3.009-1_all bug

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

       Extends "DESCRIPTION" in Mail::Reporter.

METHODS

       Extends "METHODS" in Mail::Reporter.

   Constructors
       Extends "Constructors" in Mail::Reporter.

       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                    <undef>
             log      Mail::Reporter   'WARNINGS'
             method                    'DOTLOCK'
             timeout                   10
             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).

             'FCNTLLOCK' | 'fcntllock'
                 POSIX locking via File::FcntlLock, which works on more platforms.  However, that
                 module requires a C compiler to install.

             '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

   Attributes
       $obj->expires( [SECONDS] )
           Get/Set the expiration time.  Not available for all lockers.

       $obj->timeout( [SECONDS] )
           Get/Set the timeout.  Not available for all lockers.

   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( [$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
       Extends "Error handling" in Mail::Reporter.

       $obj->AUTOLOAD()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->addReport($object)
           Inherited, see "Error handling" in Mail::Reporter

       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
       Mail::Box::Locker->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->errors()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->log( [$level, [$strings]] )
       Mail::Box::Locker->log( [$level, [$strings]] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->logPriority($level)
       Mail::Box::Locker->logPriority($level)
           Inherited, see "Error handling" in Mail::Reporter

       $obj->logSettings()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->notImplemented()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->report( [$level] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->reportAll( [$level] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->trace( [$level] )
           Inherited, see "Error handling" in Mail::Reporter

       $obj->warnings()
           Inherited, see "Error handling" in Mail::Reporter

   Cleanup
       Extends "Cleanup" in Mail::Reporter.

       $obj->DESTROY()
           When the locker is destroyed, for instance when the folder is closed or the program
           ends, the lock will be automatically removed.

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 3.009, built on August 18, 2020.
       Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2001-2020 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://dev.perl.org/licenses/