1Mail::Box::Locker(3)  User Contributed Perl Documentation Mail::Box::Locker(3)
2
3
4

NAME

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

INHERITANCE

9        Mail::Box::Locker
10          is a Mail::Reporter
11
12        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

SYNOPSIS

22        use Mail::Box::Locker;
23        my $locker = new Mail::Box::Locker(folder => $folder);
24
25        $locker->lock;
26        $locker->isLocked;
27        $locker->hasLock;
28        $locker->unlock;
29
30        use Mail::Box;
31        my $folder = Mail::Box->new(lock_method => 'DOTLOCK');
32        print $folder->locker->type;
33

DESCRIPTION

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
39       Extends "DESCRIPTION" in Mail::Reporter.
40

METHODS

42       Extends "METHODS" in Mail::Reporter.
43
44   Constructors
45       Extends "Constructors" in Mail::Reporter.
46
47       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
52           Generally the client program specifies the locking behavior through
53           options given to the folder class.
54
55            -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
64           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
69           file => FILENAME
70             Name of the file to lock.  By default, the name of the folder is
71             taken.
72
73           folder => FOLDER
74             Which FOLDER is to be locked, a Mail::Box object.
75
76           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
83             Supported locking names are
84
85             '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
91                 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
96             '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
103             '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
108             'POSIX' | 'posix'
109                 Use the POSIX standard fcntl locking.
110
111             '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
118             'MUTT'| 'mutt'
119                 Use the external program 'mutt_dotlock' to lock and unlock.
120
121             '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
126             'NONE' | 'none'
127                 Do not use locking.
128
129             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
135              my $locker = Mail::Box::Locker::MyOwn->new;
136              $folder->open(locker => $locker);
137
138           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
144             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
148           trace => LEVEL
149
150   Attributes
151       $obj->expires( [SECONDS] )
152           Get/Set the expiration time.  Not available for all lockers.
153
154       $obj->timeout( [SECONDS] )
155           Get/Set the timeout.  Not available for all lockers.
156
157   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
162           example:
163
164            print $locker->filename;
165
166       $obj->folder( [$folder] )
167           Returns the folder object which is locker.
168
169       $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
174           example:
175
176            if($locker->name eq 'FLOCK') ...
177
178   Locking
179       $obj->hasLock()
180           Check whether the folder has the lock.
181
182           example:
183
184            if($locker->hasLock) {...}
185            if($folder->locker->hasLock) {...}
186
187       $obj->isLocked()
188           Test if the folder is locked by this or a different application.
189
190           example:
191
192            if($locker->isLocked) {...}
193            if($folder->locker->isLocked) {...}
194
195       $obj->lock($folder)
196           Get a lock on a folder.  This will return false if the lock fails.
197
198           example:
199
200            die unless $locker->lock;
201            if($folder->locker->lock) {...}
202
203       $obj->unlock()
204           Undo the lock on a folder.
205
206           example:
207
208            $locker->unlock;
209            $folder->locker->unlock;
210
211   Error handling
212       Extends "Error handling" in Mail::Reporter.
213
214       $obj->AUTOLOAD()
215           Inherited, see "Error handling" in Mail::Reporter
216
217       $obj->addReport($object)
218           Inherited, see "Error handling" in Mail::Reporter
219
220       $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
226       $obj->errors()
227           Inherited, see "Error handling" in Mail::Reporter
228
229       $obj->log( [$level, [$strings]] )
230       Mail::Box::Locker->log( [$level, [$strings]] )
231           Inherited, see "Error handling" in Mail::Reporter
232
233       $obj->logPriority($level)
234       Mail::Box::Locker->logPriority($level)
235           Inherited, see "Error handling" in Mail::Reporter
236
237       $obj->logSettings()
238           Inherited, see "Error handling" in Mail::Reporter
239
240       $obj->notImplemented()
241           Inherited, see "Error handling" in Mail::Reporter
242
243       $obj->report( [$level] )
244           Inherited, see "Error handling" in Mail::Reporter
245
246       $obj->reportAll( [$level] )
247           Inherited, see "Error handling" in Mail::Reporter
248
249       $obj->trace( [$level] )
250           Inherited, see "Error handling" in Mail::Reporter
251
252       $obj->warnings()
253           Inherited, see "Error handling" in Mail::Reporter
254
255   Cleanup
256       Extends "Cleanup" in Mail::Reporter.
257
258       $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

DIAGNOSTICS

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

SEE ALSO

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

LICENSE

275       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
276       ChangeLog.
277
278       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/
280
281
282
283perl v5.36.0                      2022-07-22              Mail::Box::Locker(3)
Impressum