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
40 Constructors
41 Mail::Box::Locker->new(OPTIONS)
42 Create a new lock. You may do this directly. However, in most cases
43 the lock will not be separately instantiated but will be the second
44 class in a multiple inheritance construction with a Mail::Box.
45 Generally the client program specifies the locking behavior through
47 options given to the folder class.
48 -Option --Defined in --Default
50 expires 1 hour
51 file undef
52 folder <undef>
53 log Mail::Reporter 'WARNINGS'
54 method 'DOTLOCK'
55 timeout 10 seconds
56 trace Mail::Reporter 'WARNINGS'
57 expires => SECONDS
59 How long can a lock exist? If a different e-mail program leaves
60 a stale lock, then this lock will be removed automatically after
61 the specified number of seconds.
62 file => FILENAME
64 Name of the file to lock. By default, the name of the folder is
65 taken.
66 folder => FOLDER
68 Which FOLDER is to be locked, a Mail::Box object.
69 log => LEVEL
71 method => STRING|CLASS|ARRAY
72 Which kind of locking, specified as one of the following names as
73 STRING. You may also specify a CLASS name, or an ARRAY of names.
74 In case of an ARRAY, a 'multi' locker is started with all thee
75 full CLASS name.
76 Supported locking names are
78 'DOTLOCK' | 'dotlock'
80 The folder handler creates a file which signals that it is in
81 use. This is a bit problematic, because not all mail-
82 handling software agree on the name of the file to be
83 created.
84 On various folder types, the lockfile differs. See the
86 documentation for each folder, which describes the locking
87 strategy as well as special options to change the default
88 behavior.
89 'FLOCK' | 'flock'
91 For some folder handlers, locking is based on a file locking
92 mechanism provided by the operating system. However, this
93 does not work on all systems, such as network filesystems,
94 and such. This also doesn't work on folders based on
95 directories (Mail::Box::Dir and derived).
96 'FCNTLLOCK' | 'fcntllock'
98 POSIX locking via File::FcntlLock, which works on more
99 platforms. However, that module requires a C compiler to
100 install.
101 'POSIX' | 'posix'
103 Use the POSIX standard fcntl locking.
104 'MULTI' | 'multi'
106 Use ALL available locking methods at the same time, to have a
107 bigger chance that the folder will not be modified by some
108 other application which uses an unspecified locking method.
109 When one of the locking methods disallows access, the locking
110 fails.
111 'MUTT'| 'mutt'
113 Use the external program 'mutt_dotlock' to lock and unlock.
114 'NFS' | 'nfs'
116 A kind of "dotlock" file-locking mechanism, but adapted to
117 work over NFS. Extra precaution is needed because an "open
118 O_EXCL" on NFS is not an atomic action.
119 'NONE' | 'none'
121 Do not use locking.
122 The other option is to produce your own "Mail::Box::Locker"
124 derived class, which implements the desired locking method.
125 (Please consider offering it for inclusion in the public
126 Mail::Box module!) Create an instance of that class with this
127 parameter:
128 my $locker = Mail::Box::Locker::MyOwn->new;
130 $folder->open(locker => $locker);
131 timeout => SECONDS|'NOTIMEOUT'
133 How long to wait while trying to acquire the lock. The lock
134 request will fail when the specified number of seconds is
135 reached. If 'NOTIMEOUT' is specified, the module will wait until
136 the lock can be taken.
137 Whether it is possible to limit the wait time is platform- and
139 locking-method-specific. For instance, the `dotlock' method on
140 Windows will always wait until the lock has been received.
141 trace => LEVEL
143 The Locker
145 $obj->filename([FILENAME])
146 Returns the filename which is used to lock the folder, optionally
147 after setting it to the specified FILENAME.
148 example:
150 print $locker->filename;
152 $obj->folder([FOLDER])
154 Returns the folder object which is locker.
155 $obj->name
157 Returns the method used to lock the folder. See the new(method) for
158 details on how to specify the lock method. The name of the method
159 is returned in upper-case.
160 example:
162 if($locker->name eq 'FLOCK') ...
164 Locking
166 $obj->hasLock
167 Check whether the folder has the lock.
168 example:
170 if($locker->hasLock) {...}
172 if($folder->locker->hasLock) {...}
173 $obj->isLocked
175 Test if the folder is locked by this or a different application.
176 example:
178 if($locker->isLocked) {...}
180 if($folder->locker->isLocked) {...}
181 $obj->lock(FOLDER)
183 Get a lock on a folder. This will return false if the lock fails.
184 example:
186 die unless $locker->lock;
188 if($folder->locker->lock) {...}
189 $obj->unlock
191 Undo the lock on a folder.
192 example:
194 $locker->unlock;
196 $folder->locker->unlock;
197 Error handling
199 $obj->AUTOLOAD
200 See "Error handling" in Mail::Reporter
201 $obj->addReport(OBJECT)
203 See "Error handling" in Mail::Reporter
204 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
206 Mail::Box::Locker->defaultTrace([LEVEL]|[LOGLEVEL,
207 TRACELEVEL]|[LEVEL, CALLBACK])
208 See "Error handling" in Mail::Reporter
210 $obj->errors
212 See "Error handling" in Mail::Reporter
213 $obj->log([LEVEL [,STRINGS]])
215 Mail::Box::Locker->log([LEVEL [,STRINGS]])
216 See "Error handling" in Mail::Reporter
218 $obj->logPriority(LEVEL)
220 Mail::Box::Locker->logPriority(LEVEL)
221 See "Error handling" in Mail::Reporter
223 $obj->logSettings
225 See "Error handling" in Mail::Reporter
226 $obj->notImplemented
228 See "Error handling" in Mail::Reporter
229 $obj->report([LEVEL])
231 See "Error handling" in Mail::Reporter
232 $obj->reportAll([LEVEL])
234 See "Error handling" in Mail::Reporter
235 $obj->trace([LEVEL])
237 See "Error handling" in Mail::Reporter
238 $obj->warnings
240 See "Error handling" in Mail::Reporter
241 Cleanup
243 $obj->DESTROY
244 When the locker is destroyed, for instance when the folder is
245 closed or the program ends, the lock will be automatically removed.
246 $obj->inGlobalDestruction
248 See "Cleanup" in Mail::Reporter
249
251 Error: Package $package does not implement $method.
252 Fatal error: the specific package (or one of its superclasses) does
253 not implement this method where it should. This message means that
254 some other related classes do implement this method however the
255 class at hand does not. Probably you should investigate this and
256 probably inform the author of the package.
257
259 This module is part of Mail-Box distribution version 2.097, built on
260 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
261
263 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
264 ChangeLog.
265 This program is free software; you can redistribute it and/or modify it
267 under the same terms as Perl itself. See
268 http://www.perl.com/perl/misc/Artistic.html
269perl v5.12.3 2011-01-26 Mail::Box::Locker(3)