1Mail::Box::Locker(3) User Contributed Perl Documentation Mail::Box::Locker(3)
2
3
4
6 Mail::Box::Locker - manage the locking of mail folders
7
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
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
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
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
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.005, built on
272 March 04, 2018. Website: http://perl.overmeer.net/CPAN/
273
275 Copyrights 2001-2018 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.28.0 2018-03-04 Mail::Box::Locker(3)