=encoding utf8

=head1 NAME

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

=head1 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

=head1 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;

=head1 DESCRIPTION

Each L<Mail::Box|Mail::Box> will create its own C<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 L<"DESCRIPTION" in Mail::Reporter|Mail::Reporter/"DESCRIPTION">.

=head1 METHODS

Extends L<"METHODS" in Mail::Reporter|Mail::Reporter/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in Mail::Reporter|Mail::Reporter/"Constructors">.

=over 4

=item $class-E<gt>B<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 L<Mail::Box|Mail::Box>.

Generally the client program specifies the locking behavior through
options given to the folder class.
Improves base, see L<Mail::Reporter/"Constructors">

 -Option --Default
  expires  1 hour
  file     undef
  folder   <C<undef>>
  method   'DOTLOCK'
  timeout  10

=over 2

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

=item file => $file

Name of the C<$file> to lock.  By default, the name of the folder is taken.

=item folder => $folder

Which C<$folder> is to be locked, a L<Mail::Box|Mail::Box> object.

=item method => $name|CLASS|\@names

Which kind of locking, specified as one of the following tokens as C<$name>.
You may also specify a CLASS name, or multiple C<@names>.  In the latter case,
a 'multi' locker is started with all the specified C<@names>.

Supported locking method names are (lower-case is also accepted)

=over 4

=item '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.

=item '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 (L<Mail::Box::Dir|Mail::Box::Dir> and derived).

=item 'FCNTLLOCK'

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

=item 'POSIX'

Use the POSIX standard fcntl locking.

=item '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.

=item 'MUTT'

Use the external program 'mutt_dotlock' to lock and unlock.

=item 'NFS'

A kind of C<dotlock> file-locking mechanism, but adapted to work over
NFS.  Extra precaution is needed because an C<open O_EXCL> on NFS is
not an atomic action.

=item 'NONE'

Do not use locking.

=back

The other option is to produce your own C<Mail::Box::Locker> derived class,
which implements the desired locking method. (Please consider offering it
for inclusion in the public L<Mail::Box|Mail::Box> module!) Create an instance of that
class with this parameter:

  my $locker = Mail::Box::Locker::MyOwn->new;
  $folder->open(locker => $locker);

=item timeout => $seconds|'NOTIMEOUT'

How long to wait while trying to acquire the lock. The lock request will
fail when the specified number of C<$seconds> is reached.  If C<'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.

=back

=back

=head2 Attributes

Extends L<"Attributes" in Mail::Reporter|Mail::Reporter/"Attributes">.

=over 4

=item $obj-E<gt>B<expires>( [SECONDS] )

Get/Set the expiration time.  Not available for all lockers.

=item $obj-E<gt>B<filename>( [$filename] )

Returns the filename which is used to lock the folder, optionally after
setting it to the specified C<$filename>.

» example: 

  print $locker->filename;

=item $obj-E<gt>B<folder>( [$folder] )

Returns the folder object which is locker.

=item $obj-E<gt>B<name>()

Returns the method used to lock the folder. See the L<new(method)|Mail::Box::Locker/"METHODS"> 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') ...

=item $obj-E<gt>B<timeout>( [SECONDS] )

Get/Set the timeout.  Not available for all lockers.

=back

=head2 Locking

=over 4

=item $obj-E<gt>B<hasLock>()

Check whether the folder has the lock.

» example: 

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

=item $obj-E<gt>B<isLocked>()

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

» example: 

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

=item $obj-E<gt>B<lock>($folder)

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

» example: 

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

=item $obj-E<gt>B<unlock>()

Undo the lock on a folder.

» example: 

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

=back

=head2 Error handling

Extends L<"Error handling" in Mail::Reporter|Mail::Reporter/"Error handling">.

=over 4

=item $obj-E<gt>B<AUTOLOAD>()

Inherited, see L<Mail::Reporter/"Error handling">

=item $obj-E<gt>B<notImplemented>()

Inherited, see L<Mail::Reporter/"Error handling">

=back

=head2 Cleanup

Extends L<"Cleanup" in Mail::Reporter|Mail::Reporter/"Cleanup">.

=over 4

=item $obj-E<gt>B<DESTROY>()

When the locker is destroyed, for instance when the folder is closed
or the program ends, the lock will be automatically removed.
Improves base, see L<Mail::Reporter/"Cleanup">

=back

=head1 DIAGNOSTICS

=over 4

=item Error: class $package does not implement method $method.

Fatal error: the specific C<$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.
Cast by C<notImplemented()>

=item Error: failed to use locking module $class: $@

Cast by C<new()>

=item Error: no locking method $name defined: use @avail

Cast by C<new()>

=back

=head1 SEE ALSO

This module is part of Mail-Box version 4.01,
built on December 13, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2001-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.