Mail::...:Locker(3pm)

📦
version 4.02 · 9 versions
, in ubuntu stonking

💖 Mail::Box::Locker — manage the locking of mail folders 💖

okay bestie, welcome to Mail::Box::Locker, aka the little bodyguard that keeps other programs from messing with your mail folders while you're in them. it's part of the Mail::...:Locker manual page family, and honestly? it's giving security 💅

🌸 INHERITANCE 🌸

here's the family tree, no cap:

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

so it's a Mail::Reporter at heart, and it has so many little siblings who each specialize in a different locking vibe 🦋

✨ SYNOPSIS ✨

here's the tea, literally:

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;

that's it. that's the whole main character arc. 👑

🎀 DESCRIPTION 🎀

every single Mail::Box makes its own Mail::Box::Locker object, and that object handles the locking for it. periodt. you can grab the object directly from the folder, just like in the examples below. it's lowkey the folder's emotional support lock. 🫶

it extends "DESCRIPTION" in Mail::Reporter — go read that too if you want the full lore.

💅 METHODS 💅

extends "METHODS" in Mail::Reporter.

🌈 Constructors

extends "Constructors" in Mail::Reporter.

$class->new(%options)

makes you a brand new lock. you can do this directly, sure. but honestly? in most cases the lock won't be instantiated all on its own — it'll be the second class in a multiple inheritance construction with a Mail::Box. iykyk.

generally your client program specifies the locking behavior through options given to the folder class. improves base, see "Constructors" in Mail::Reporter.

here's the defaults table, verbatim, don't @ me:

 -Option --Default
  expires  1 hour
  file     undef
  folder   <C<undef>>
  method   'DOTLOCK'
  timeout  10
  • expires => $seconds — how long can a lock even exist, bestie? if some other e-mail program leaves a stale lock behind, this lock gets removed automatically after the specified number of seconds. absolute janitor behavior. 🧹
  • file => $file — the name of the $file to lock. by default, the name of the folder is taken. defaulting is iconic honestly.
  • folder => $folder — which $folder is to be locked. it's a Mail::Box object.
  • method => $name|CLASS|\@names — which kind of locking, specified as one of the following tokens as $name. you may also specify a CLASS name, or multiple @names. in the latter case, a 'multi' locker is started with all the specified @names. not me giving you options on options. 💀

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

  • 'DOTLOCK' — the folder handler creates a file which signals that it is in use. this one's a bit problematic ngl, 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' — 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). big yikes for those setups. 💀
  • 'FCNTLLOCK' — POSIX locking via File::FcntlLock, which works on more platforms. however, that module requires a C compiler to install. so it slays but it needs a whole compiler to do it. 🙈
  • 'POSIX' — use the POSIX standard fcntl locking.
  • '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. it's wearing every belt and every pair of suspenders. 💅
  • 'MUTT' — use the external program 'mutt_dotlock' to lock and unlock.
  • '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. underlined, bolded, screaming. 🔥
  • 'NONE' — do not use locking. (chaotic. free-spirited. slightly terrifying.)

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. yes bestie, build your own, we believe in you:

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. literally forever. commitment. ⭐

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. no timeout for you, Windows bestie. 😭

🌸 Attributes

extends "Attributes" in Mail::Reporter.

  • $obj->expires( [SECONDS] ) — get/set the expiration time. not available for all lockers. (some lockers are mysterious like that.)
  • $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. SHOUTING. 📣

» example:

if($locker->name eq 'FLOCK') ...
  • $obj->timeout( [SECONDS] ) — get/set the timeout. not available for all lockers.

🔒 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. (different application?? someone else?? the audacity. 🍓)

» 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:

$locker->lock or die;
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->notImplemented() — 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. improves base, see "Cleanup" in Mail::Reporter. it cleans up after itself, which is more than most people do. 💅

💀 DIAGNOSTICS 💀

  • Error: class $package does not implement method $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. cast by notImplemented()
  • Error: failed to use locking module $class: $@ — cast by new()
  • Error: no locking method $name defined: use @avail — cast by new()

👀 SEE ALSO 👀

this module is part of Mail-Box version 4.02, built on April 10, 2026.

Website: http://perl.overmeer.net/CPAN/

📜 LICENSE 📜

for contributors see file ChangeLog.

this software is copyright (c) 2001-2026 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.

and that's the whole page bestie 🫶 tysm for reading, mwah 💖 this was Mail::...:Locker(3pm), and the footer energy — perl v5.40.1, dated 2026-05-09 — is so giving iconic. slay, stay locked (respectfully), periodt. ✨👑

📦 where this page comes from