1Mail::Box::Locker(3) User Contributed Perl Documentation Mail::Box::Locker(3)
2
6 Mail::Box::Locker - manage the locking of mail folders
7
9 Mail::Box::Locker
10 is a Mail::Reporter
11 Mail::Box::Locker is extended by
13 Mail::Box::Locker::DotLock
14 Mail::Box::Locker::FcntlLock
15 Mail::Box::Locker::Flock
16 Mail::Box::Locker::Multi
17 Mail::Box::Locker::Mutt
18 Mail::Box::Locker::NFS
19 Mail::Box::Locker::POSIX
20
22 use Mail::Box::Locker;
23 my $locker = new Mail::Box::Locker(folder => $folder);
24 $locker->lock;
26 $locker->isLocked;
27 $locker->hasLock;
28 $locker->unlock;
29 use Mail::Box;
31 my $folder = Mail::Box->new(lock_method => 'DOTLOCK');
32 print $folder->locker->type;
33
35 Each Mail::Box will create its own "Mail::Box::Locker" object which
36 will handle the locking for it. You can access of the object directly
37 from the folder, as shown in the examples below.
38 Extends "DESCRIPTION" in Mail::Reporter.
40
42 Extends "METHODS" in Mail::Reporter.
43 Constructors
45 Extends "Constructors" in Mail::Reporter.
46 Mail::Box::Locker->new(%options)
48 Create a new lock. You may do this directly. However, in most cases
49 the lock will not be separately instantiated but will be the second
50 class in a multiple inheritance construction with a Mail::Box.
51 Generally the client program specifies the locking behavior through
53 options given to the folder class.
54 -Option --Defined in --Default
56 expires 1 hour
57 file undef
58 folder <undef>
59 log Mail::Reporter 'WARNINGS'
60 method 'DOTLOCK'
61 timeout 10
62 trace Mail::Reporter 'WARNINGS'
63 expires => SECONDS
65 How long can a lock exist? If a different e-mail program leaves
66 a stale lock, then this lock will be removed automatically after
67 the specified number of seconds.
68 file => FILENAME
70 Name of the file to lock. By default, the name of the folder is
71 taken.
72 folder => FOLDER
74 Which FOLDER is to be locked, a Mail::Box object.
75 log => LEVEL
77 method => STRING|CLASS|ARRAY
78 Which kind of locking, specified as one of the following names as
79 STRING. You may also specify a CLASS name, or an ARRAY of names.
80 In case of an ARRAY, a 'multi' locker is started with all thee
81 full CLASS name.
82 Supported locking names are
84 'DOTLOCK' | 'dotlock'
86 The folder handler creates a file which signals that it is in
87 use. This is a bit problematic, because not all mail-
88 handling software agree on the name of the file to be
89 created.
90 On various folder types, the lockfile differs. See the
92 documentation for each folder, which describes the locking
93 strategy as well as special options to change the default
94 behavior.
95 'FLOCK' | 'flock'
97 For some folder handlers, locking is based on a file locking
98 mechanism provided by the operating system. However, this
99 does not work on all systems, such as network filesystems,
100 and such. This also doesn't work on folders based on
101 directories (Mail::Box::Dir and derived).
102 'FCNTLLOCK' | 'fcntllock'
104 POSIX locking via File::FcntlLock, which works on more
105 platforms. However, that module requires a C compiler to
106 install.
107 'POSIX' | 'posix'
109 Use the POSIX standard fcntl locking.
110 'MULTI' | 'multi'
112 Use ALL available locking methods at the same time, to have a
113 bigger chance that the folder will not be modified by some
114 other application which uses an unspecified locking method.
115 When one of the locking methods disallows access, the locking
116 fails.
117 'MUTT'| 'mutt'
119 Use the external program 'mutt_dotlock' to lock and unlock.
120 'NFS' | 'nfs'
122 A kind of "dotlock" file-locking mechanism, but adapted to
123 work over NFS. Extra precaution is needed because an "open
124 O_EXCL" on NFS is not an atomic action.
125 'NONE' | 'none'
127 Do not use locking.
128 The other option is to produce your own "Mail::Box::Locker"
130 derived class, which implements the desired locking method.
131 (Please consider offering it for inclusion in the public
132 Mail::Box module!) Create an instance of that class with this
133 parameter:
134 my $locker = Mail::Box::Locker::MyOwn->new;
136 $folder->open(locker => $locker);
137 timeout => SECONDS|'NOTIMEOUT'
139 How long to wait while trying to acquire the lock. The lock
140 request will fail when the specified number of seconds is
141 reached. If 'NOTIMEOUT' is specified, the module will wait until
142 the lock can be taken.
143 Whether it is possible to limit the wait time is platform- and
145 locking-method-specific. For instance, the `dotlock' method on
146 Windows will always wait until the lock has been received.
147 trace => LEVEL
149 Attributes
151 $obj->expires( [SECONDS] )
152 Get/Set the expiration time. Not available for all lockers.
153 $obj->timeout( [SECONDS] )
155 Get/Set the timeout. Not available for all lockers.
156 The Locker
158 $obj->filename( [$filename] )
159 Returns the filename which is used to lock the folder, optionally
160 after setting it to the specified $filename.
161 example:
163 print $locker->filename;
165 $obj->folder( [$folder] )
167 Returns the folder object which is locker.
168 $obj->name()
170 Returns the method used to lock the folder. See the new(method) for
171 details on how to specify the lock method. The name of the method
172 is returned in upper-case.
173 example:
175 if($locker->name eq 'FLOCK') ...
177 Locking
179 $obj->hasLock()
180 Check whether the folder has the lock.
181 example:
183 if($locker->hasLock) {...}
185 if($folder->locker->hasLock) {...}
186 $obj->isLocked()
188 Test if the folder is locked by this or a different application.
189 example:
191 if($locker->isLocked) {...}
193 if($folder->locker->isLocked) {...}
194 $obj->lock($folder)
196 Get a lock on a folder. This will return false if the lock fails.
197 example:
199 die unless $locker->lock;
201 if($folder->locker->lock) {...}
202 $obj->unlock()
204 Undo the lock on a folder.
205 example:
207 $locker->unlock;
209 $folder->locker->unlock;
210 Error handling
212 Extends "Error handling" in Mail::Reporter.
213 $obj->AUTOLOAD()
215 Inherited, see "Error handling" in Mail::Reporter
216 $obj->addReport($object)
218 Inherited, see "Error handling" in Mail::Reporter
219 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
221 $callback] )
222 Mail::Box::Locker->defaultTrace( [$level]|[$loglevel,
223 $tracelevel]|[$level, $callback] )
224 Inherited, see "Error handling" in Mail::Reporter
225 $obj->errors()
227 Inherited, see "Error handling" in Mail::Reporter
228 $obj->log( [$level, [$strings]] )
230 Mail::Box::Locker->log( [$level, [$strings]] )
231 Inherited, see "Error handling" in Mail::Reporter
232 $obj->logPriority($level)
234 Mail::Box::Locker->logPriority($level)
235 Inherited, see "Error handling" in Mail::Reporter
236 $obj->logSettings()
238 Inherited, see "Error handling" in Mail::Reporter
239 $obj->notImplemented()
241 Inherited, see "Error handling" in Mail::Reporter
242 $obj->report( [$level] )
244 Inherited, see "Error handling" in Mail::Reporter
245 $obj->reportAll( [$level] )
247 Inherited, see "Error handling" in Mail::Reporter
248 $obj->trace( [$level] )
250 Inherited, see "Error handling" in Mail::Reporter
251 $obj->warnings()
253 Inherited, see "Error handling" in Mail::Reporter
254 Cleanup
256 Extends "Cleanup" in Mail::Reporter.
257 $obj->DESTROY()
259 When the locker is destroyed, for instance when the folder is
260 closed or the program ends, the lock will be automatically removed.
261
263 Error: Package $package does not implement $method.
264 Fatal error: the specific package (or one of its superclasses) does
265 not implement this method where it should. This message means that
266 some other related classes do implement this method however the
267 class at hand does not. Probably you should investigate this and
268 probably inform the author of the package.
269
271 This module is part of Mail-Box distribution version 3.009, built on
272 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
273
275 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
276 ChangeLog.
277 This program is free software; you can redistribute it and/or modify it
279 under the same terms as Perl itself. See http://dev.perl.org/licenses/
280perl v5.36.0 2023-01-20 Mail::Box::Locker(3)