Mail::Box::Locker(3pm)

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::Flock
15          Mail::Box::Locker::Multi
16          Mail::Box::Locker::Mutt
17          Mail::Box::Locker::NFS
18          Mail::Box::Locker::POSIX
19

SYNOPSIS

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

DESCRIPTION

34       Each Mail::Box will create its own "Mail::Box::Locker" object which
35       will handle the locking for it.  You can access of the object directly
36       from the folder, as shown in the examples below.
37

METHODS

39       Constructors
40
41       Mail::Box::Locker->new(OPTIONS)
42
43           Create a new lock. You may do this directly. However, in most cases
44           the lock will not be separately instantiated but will be the second
45           class in a multiple inheritance construction with a Mail::Box.
46
47           Generally the client program specifies the locking behavior through
48           options given to the folder class.
49
50            Option --Defined in     --Default
51            expires                   1 hour
52            file                      undef
53            folder                    <required>
54            log      Mail::Reporter   'WARNINGS'
55            method                    'DOTLOCK'
56            timeout                   10 seconds
57            trace    Mail::Reporter   'WARNINGS'
58
59           . expires SECONDS
60
61               How long can a lock exist?  If a different e-mail program
62               leaves a stale lock, then this lock will be removed automati‐
63               cally after the specified number of seconds.
64
65           . file FILENAME
66
67               Name of the file to lock.  By default, the name of the folder
68               is taken.
69
70           . folder FOLDER
71
72               Which FOLDER is to be locked, a Mail::Box object.
73
74           . log LEVEL
75
76           . method STRING⎪CLASS⎪ARRAY
77
78               Which kind of locking, specified as one of the following names
79               as STRING.  You may also specify a CLASS name, or an ARRAY of
80               names.  In case of an ARRAY, a 'multi' locker is started with
81               all thee 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
87                   in use.  This is a bit problematic, because not all mail-
88                   handling software agree on the name of the file to be cre‐
89                   ated.
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 lock‐
98                   ing mechanism provided by the operating system.  However,
99                   this does not work on all systems, such as network filesys‐
100                   tems, and such. This also doesn't work on folders based on
101                   directories (Mail::Box::Dir and derived).
102
103               'POSIX' ⎪ 'posix'
104                   Use the POSIX standard fcntl locking.
105
106               'MULTI' ⎪ 'multi'
107                   Use ALL available locking methods at the same time, to have
108                   a bigger chance that the folder will not be modified by
109                   some other application which uses an unspecified locking
110                   method.  When one of the locking methods disallows access,
111                   the locking fails.
112
113               'MUTT'⎪ 'mutt'
114                   Use the external program 'mutt_dotlock' to lock and unlock.
115
116               'NFS' ⎪ 'nfs'
117                   A kind of "dotlock" file-locking mechanism, but adapted to
118                   work over NFS.  Extra precaution is needed because an "open
119                   O_EXCL" on NFS is not an atomic action.
120
121               'NONE' ⎪ 'none'
122                   Do not use locking.
123
124               The other option is to produce your own "Mail::Box::Locker"
125               derived class, which implements the desired locking method.
126               (Please consider offering it for inclusion in the public
127               Mail::Box module!) Create an instance of that class with this
128               parameter:
129
130                my $locker = Mail::Box::Locker::MyOwn->new;
131                $folder->open(locker => $locker);
132
133           . timeout SECONDS⎪'NOTIMEOUT'
134
135               How long to wait while trying to acquire the lock. The lock
136               request will fail when the specified number of seconds is
137               reached.  If 'NOTIMEOUT' is specified, the module will wait
138               until the lock can be taken.
139
140               Whether it is possible to limit the wait time is platform- and
141               locking-method-specific.  For instance, the `dotlock' method on
142               Windows will always wait until the lock has been received.
143
144           . trace LEVEL
145
146       The Locker
147
148       $obj->filename([FILENAME])
149
150           Returns the filename which is used to lock the folder, optionally
151           after setting it to the specified FILENAME.
152
153           Example:
154
155            print $locker->filename;
156
157       $obj->folder
158
159           Returns the folder object which is locker.
160
161       $obj->name
162
163           Returns the method used to lock the folder. See the new(method) for
164           details on how to specify the lock method.  The name of the method
165           is returned in upper-case.
166
167           Example:
168
169            if($locker->name eq 'FLOCK') ...
170
171       Locking
172
173       $obj->hasLock
174
175           Check whether the folder has the lock.
176
177           Example:
178
179            if($locker->hasLock) {...}
180            if($folder->locker->hasLock) {...}
181
182       $obj->isLocked
183
184           Test if the folder is locked by this or a different application.
185
186           Example:
187
188            if($locker->isLocked) {...}
189            if($folder->locker->isLocked) {...}
190
191       $obj->lock(FOLDER)
192
193           Get a lock on a folder.  This will return false if the lock fails.
194
195           Example:
196
197            die unless $locker->lock;
198            if($folder->locker->lock) {...}
199
200       $obj->unlock
201
202           Undo the lock on a folder.
203
204           Example:
205
206            $locker->unlock;
207            $folder->locker->unlock;
208
209       Error handling
210
211       $obj->AUTOLOAD
212
213           See "Error handling" in Mail::Reporter
214
215       $obj->addReport(OBJECT)
216
217           See "Error handling" in Mail::Reporter
218
219       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
220
221       Mail::Box::Locker->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
222       CALLBACK])
223
224           See "Error handling" in Mail::Reporter
225
226       $obj->errors
227
228           See "Error handling" in Mail::Reporter
229
230       $obj->log([LEVEL [,STRINGS]])
231
232       Mail::Box::Locker->log([LEVEL [,STRINGS]])
233
234           See "Error handling" in Mail::Reporter
235
236       $obj->logPriority(LEVEL)
237
238       Mail::Box::Locker->logPriority(LEVEL)
239
240           See "Error handling" in Mail::Reporter
241
242       $obj->logSettings
243
244           See "Error handling" in Mail::Reporter
245
246       $obj->notImplemented
247
248           See "Error handling" in Mail::Reporter
249
250       $obj->report([LEVEL])
251
252           See "Error handling" in Mail::Reporter
253
254       $obj->reportAll([LEVEL])
255
256           See "Error handling" in Mail::Reporter
257
258       $obj->trace([LEVEL])
259
260           See "Error handling" in Mail::Reporter
261
262       $obj->warnings
263
264           See "Error handling" in Mail::Reporter
265
266       Cleanup
267
268       $obj->DESTROY
269
270           When the locker is destroyed, for instance when the folder is
271           closed or the program ends, the lock will be automatically removed.
272
273       $obj->inGlobalDestruction
274
275           See "Cleanup" in Mail::Reporter
276

DIAGNOSTICS

278       Error: Package $package does not implement $method.
279
280       Fatal error: the specific package (or one of its superclasses) does not
281       implement this method where it should. This message means that some
282       other related classes do implement this method however the class at
283       hand does not.  Probably you should investigate this and probably
284       inform the author of the package.
285

LICENSE

291       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
292       ChangeLog.
293
294       This program is free software; you can redistribute it and/or modify it
295       under the same terms as Perl itself.  See
296       http://www.perl.com/perl/misc/Artistic.html
297
298
299
300perl v5.8.8                       2007-03-25              Mail::Box::Locker(3)