1IPC::Shareable(3) User Contributed Perl Documentation IPC::Shareable(3)
2
6 IPC::Shareable - share Perl variables between processes
7
9 use IPC::Shareable (':lock');
10 tie SCALAR, 'IPC::Shareable', GLUE, OPTIONS;
11 tie ARRAY, 'IPC::Shareable', GLUE, OPTIONS;
12 tie HASH, 'IPC::Shareable', GLUE, OPTIONS;
13 (tied VARIABLE)->shlock;
15 (tied VARIABLE)->shunlock;
16 (tied VARIABLE)->shlock(LOCK_SH⎪LOCK_NB)
18 or print "resource unavailable\n";
19 (tied VARIABLE)->remove;
21 IPC::Shareable->clean_up;
23 IPC::Shareable->clean_up_all;
24
26 The occurrence of a number in square brackets, as in [N], in the text
27 of this document refers to a numbered note in the "NOTES".
28
30 IPC::Shareable allows you to tie a variable to shared memory making it
31 easy to share the contents of that variable with other Perl processes.
32 Scalars, arrays, and hashes can be tied. The variable being tied may
33 contain arbitrarily complex data structures - including references to
34 arrays, hashes of hashes, etc.
35 The association between variables in distinct processes is provided by
37 GLUE. This is an integer number or 4 character string[1] that serves
38 as a common identifier for data across process space. Hence the state‐
39 ment
40 tie $scalar, 'IPC::Shareable', 'data';
42 in program one and the statement
44 tie $variable, 'IPC::Shareable', 'data';
46 in program two will bind $scalar in program one and $variable in pro‐
48 gram two.
49 There is no pre-set limit to the number of processes that can bind to
51 data; nor is there a pre-set limit to the complexity of the underlying
52 data of the tied variables[2]. The amount of data that can be shared
53 within a single bound variable is limited by the system's maximum size
54 for a shared memory segment (the exact value is system-dependent).
55 The bound data structures are all linearized (using Raphael Manfredi's
57 Storable module) before being slurped into shared memory. Upon
58 retrieval, the original format of the data structure is recovered.
59 Semaphore flags can be used for locking data between competing pro‐
60 cesses.
61
63 Options are specified by passing a reference to a hash as the fourth
64 argument to the tie() function that enchants a variable. Alternatively
65 you can pass a reference to a hash as the third argument; IPC::Share‐
66 able will then look at the field named key in this hash for the value
67 of GLUE. So,
68 tie $variable, 'IPC::Shareable', 'data', \%options;
70 is equivalent to
72 tie $variable, 'IPC::Shareable', { key => 'data', ... };
74 Boolean option values can be specified using a value that evaluates to
76 either true or false in the Perl sense.
77 NOTE: Earlier versions allowed you to use the word yes for true and the
79 word no for false, but support for this "feature" is being removed.
80 yes will still act as true (since it is true, in the Perl sense), but
81 use of the word no now emits an (optional) warning and then converts to
82 a false value. This warning will become mandatory in a future release
83 and then at some later date the use of no will stop working altogether.
84 The following fields are recognized in the options hash.
86 key The key field is used to determine the GLUE when using the three-
88 argument form of the call to tie(). This argument is then, in
89 turn, used as the KEY argument in subsequent calls to shmget() and
90 semget().
91 The default value is IPC_PRIVATE, meaning that your variables can‐
93 not be shared with other processes.
94 create
96 create is used to control whether calls to tie() create new shared
97 memory segments or not. If create is set to a true value,
98 IPC::Shareable will create a new binding associated with GLUE as
99 needed. If create is false, IPC::Shareable will not attempt to
100 create a new shared memory segment associated with GLUE. In this
101 case, a shared memory segment associated with GLUE must already
102 exist or the call to tie() will fail and return undef. The default
103 is false.
104 exclusive
106 If exclusive field is set to a true value, calls to tie() will fail
107 (returning undef) if a data binding associated with GLUE already
108 exists. If set to a false value, calls to tie() will succeed even
109 if a shared memory segment associated with GLUE already exists.
110 The default is false
111 mode
113 The mode argument is an octal number specifying the access permis‐
114 sions when a new data binding is being created. These access per‐
115 mission are the same as file access permissions in that 0666 is
116 world readable, 0600 is readable only by the effective UID of the
117 process creating the shared variable, etc. The default is 0666
118 (world readable and writable).
119 destroy
121 If set to a true value, the shared memory segment underlying the
122 data binding will be removed when the process calling tie() exits
123 (gracefully)[3]. Use this option with care. In particular you
124 should not use this option in a program that will fork after bind‐
125 ing the data. On the other hand, shared memory is a finite
126 resource and should be released if it is not needed. The default
127 is false
128 size
130 This field may be used to specify the size of the shared memory
131 segment allocated. The default is IPC::Shareable::SHM_BUFSIZ().
132 Default values for options are
134 key => IPC_PRIVATE,
136 create => 0,
137 exclusive => 0,
138 destroy => 0,
139 mode => 0,
140 size => IPC::Shareable::SHM_BUFSIZ(),
141
143 IPC::Shareable provides methods to implement application-level advisory
144 locking of the shared data structures. These methods are called
145 shlock() and shunlock(). To use them you must first get the object
146 underlying the tied variable, either by saving the return value of the
147 original call to tie() or by using the built-in tied() function.
148 To lock a variable, do this:
150 $knot = tie $sv, 'IPC::Shareable', $glue, { %options };
152 ...
153 $knot->shlock;
154 or equivalently
156 tie($scalar, 'IPC::Shareable', $glue, { %options });
158 (tied $scalar)->shlock;
159 This will place an exclusive lock on the data of $scalar. You can also
161 get shared locks or attempt to get a lock without blocking.
162 IPC::Shareable makes the constants LOCK_EX, LOCK_SH, LOCK_UN, and
163 LOCK_NB exportable to your address space with the export tags ":lock",
164 ":flock", or ":all". The values should be the same as the standard
165 "flock" option arguments.
166 if ( (tied $scalar)->shlock(LOCK_SH⎪LOCK_NB) ) {
168 print "The value is $scalar\n";
169 (tied $scalar)->shunlock;
170 } else {
171 print "Another process has an exlusive lock.\n";
172 }
173 If no argument is provided to "shlock", it defaults to LOCK_EX. To
175 unlock a variable do this:
176 $knot->shunlock;
178 or
180 (tied $scalar)->shunlock;
182 or
184 $knot->shlock(LOCK_UN); # Same as calling shunlock
186 There are some pitfalls regarding locking and signals about which you
188 should make yourself aware; these are discussed in "NOTES".
189 If you use the advisory locking, IPC::Shareable assumes that you know
191 what you are doing and attempts some optimizations. When you obtain a
192 lock, either exclusive or shared, a fetch and thaw of the data is per‐
193 formed. No additional fetch/thaw operations are performed until you
194 release the lock and access the bound variable again. During the time
195 that the lock is kept, all accesses are perfomed on the copy in program
196 memory. If other processes do not honor the lock, and update the
197 shared memory region unfairly, the process with the lock will not be in
198 sync. In other words, IPC::Shareable does not enforce the lock for
199 you.
200 A similar optimization is done if you obtain an exclusive lock.
202 Updates to the shared memory region will be postponed until you release
203 the lock (or downgrade to a shared lock).
204 Use of locking can significantly improve performance for operations
206 such as iterating over an array, retrieving a list from a slice or
207 doing a slice assignment.
208
210 When a reference to a non-tied scalar, hash, or array is assigned to a
211 tie()d variable, IPC::Shareable will attempt to tie() the thingy being
212 referenced[4]. This allows disparate processes to see changes to not
213 only the top-level variable, but also changes to nested data. This
214 feature is intended to be transparent to the application, but there are
215 some caveats to be aware of.
216 First of all, IPC::Shareable does not (yet) guarantee that the ids
218 shared memory segments allocated automagically are unique. The more
219 automagical tie()ing that happens, the greater the chance of a colli‐
220 sion.
221 Secondly, since a new shared memory segment is created for each thingy
223 being referenced, the liberal use of references could cause the system
224 to approach its limit for the total number of shared memory segments
225 allowed.
226
228 IPC::Shareable implements tie()ing objects to shared memory too. Since
229 an object is just a reference, the same principles (and caveats) apply
230 to tie()ing objects as other reference types.
231
233 perl(1) will destroy the object underlying a tied variable when then
234 tied variable goes out of scope. Unfortunately for IPC::Shareable,
235 this may not be desirable: other processes may still need a handle on
236 the relevant shared memory segment. IPC::Shareable therefore provides
237 an interface to allow the application to control the timing of removal
238 of shared memory segments. The interface consists of three methods -
239 remove(), clean_up(), and clean_up_all() - and the destroy option to
240 tie().
241 destroy option
243 As described in "OPTIONS", specifying the destroy option when
244 tie()ing a variable coerces IPC::Shareable to remove the underlying
245 shared memory segment when the process calling tie() exits grace‐
246 fully. Note that any related shared memory segments created
247 automagically by the use of references will also be removed.
248 remove()
250 (tied $var)->remove;
251 Calling remove() on the object underlying a tie()d variable removes
253 the associated shared memory segment. The segment is removed irre‐
254 spective of whether it has the destroy option set or not and irre‐
255 spective of whether the calling process created the segment.
256 clean_up()
258 IPC::Shareable->clean_up;
259 This is a class method that provokes IPC::Shareable to remove all
261 shared memory segments created by the process. Segments not cre‐
262 ated by the calling process are not removed.
263 clean_up_all()
265 IPC::Shareable->clean_up_all;
266 This is a class method that provokes IPC::Shareable to remove all
268 shared memory segments encountered by the process. Segments are
269 removed even if they were not created by the calling process.
270
272 In a file called server:
273 #!/usr/bin/perl -w
275 use strict;
276 use IPC::Shareable;
277 my $glue = 'data';
278 my %options = (
279 create => 'yes',
280 exclusive => 0,
281 mode => 0644,
282 destroy => 'yes',
283 );
284 my %colours;
285 tie %colours, 'IPC::Shareable', $glue, { %options } or
286 die "server: tie failed\n";
287 %colours = (
288 red => [
289 'fire truck',
290 'leaves in the fall',
291 ],
292 blue => [
293 'sky',
294 'police cars',
295 ],
296 );
297 ((print "server: there are 2 colours\n"), sleep 5)
298 while scalar keys %colours == 2;
299 print "server: here are all my colours:\n";
300 foreach my $c (keys %colours) {
301 print "server: these are $c: ",
302 join(', ', @{$colours{$c}}), "\n";
303 }
304 exit;
305 In a file called client
307 #!/usr/bin/perl -w
309 use strict;
310 use IPC::Shareable;
311 my $glue = 'data';
312 my %options = (
313 create => 0,
314 exclusive => 0,
315 mode => 0644,
316 destroy => 0,
317 );
318 my %colours;
319 tie %colours, 'IPC::Shareable', $glue, { %options } or
320 die "client: tie failed\n";
321 foreach my $c (keys %colours) {
322 print "client: these are $c: ",
323 join(', ', @{$colours{$c}}), "\n";
324 }
325 delete $colours{'red'};
326 exit;
327 And here is the output (the sleep commands in the command line prevent
329 the output from being interrupted by shell prompts):
330 bash$ ( ./server & ) ; sleep 10 ; ./client ; sleep 10
332 server: there are 2 colours
333 server: there are 2 colours
334 server: there are 2 colours
335 client: these are blue: sky, police cars
336 client: these are red: fire truck, leaves in the fall
337 server: here are all my colours:
338 server: these are blue: sky, police cars
339
341 Calls to tie() that try to implement IPC::Shareable will return true if
342 successful, undef otherwise. The value returned is an instance of the
343 IPC::Shareable class.
344
346 Benjamin Sugars <bsugars@canoe.ca>
347
349 Footnotes from the above sections
350 1 If GLUE is longer than 4 characters, only the 4 most significant
352 characters are used. These characters are turned into integers by
353 unpack()ing them. If GLUE is less than 4 characters, it is space
354 padded.
355 2 IPC::Shareable provides no pre-set limits, but the system does.
357 Namely, there are limits on the number of shared memory segments
358 that can be allocated and the total amount of memory usable by
359 shared memory.
360 3 If the process has been smoked by an untrapped signal, the binding
362 will remain in shared memory. If you're cautious, you might try
363 $SIG{INT} = \&catch_int;
365 sub catch_int {
366 die;
367 }
368 ...
369 tie $variable, IPC::Shareable, 'data', { 'destroy' => 'Yes!' };
370 which will at least clean up after your user hits CTRL-C because
372 IPC::Shareable's END method will be called. Or, maybe you'd like
373 to leave the binding in shared memory, so subsequent process can
374 recover the data...
375 4 This behaviour is markedly different from previous versions of
377 IPC::Shareable. Older versions would sometimes tie() referenced
378 thingies, and sometimes not. The new approach is more reliable (I
379 think) and predictable (certainly) but uses more shared memory seg‐
380 ments.
381 General Notes
383 o When using shlock() to lock a variable, be careful to guard against
385 signals. Under normal circumstances, IPC::Shareable's END method
386 unlocks any locked variables when the process exits. However, if
387 an untrapped signal is received while a process holds an exclusive
388 lock, DESTROY will not be called and the lock may be maintained
389 even though the process has exited. If this scares you, you might
390 be better off implementing your own locking methods.
391 One advantage of using "flock" on some known file instead of the
393 locking implemented with semaphores in IPC::Shareable is that when
394 a process dies, it automatically releases any locks. This only
395 happens with IPC::Shareable if the process dies gracefully. The
396 alternative is to attempt to account for every possible calamitous
397 ending for your process (robust signal handling in Perl is a source
398 of much debate, though it usually works just fine) or to become
399 familiar with your system's tools for removing shared memory and
400 semaphores. This concern should be balanced against the signifi‐
401 cant performance improvements you can gain for larger data struc‐
402 tures by using the locking mechanism implemented in IPC::Shareable.
403 o There is a program called ipcs(1/8) (and ipcrm(1/8)) that is avail‐
405 able on at least Solaris and Linux that might be useful for clean‐
406 ing moribund shared memory segments or semaphore sets produced by
407 bugs in either IPC::Shareable or applications using it.
408 o This version of IPC::Shareable does not understand the format of
410 shared memory segments created by versions prior to 0.60. If you
411 try to tie to such segments, you will get an error. The only work
412 around is to clear the shared memory segments and start with a
413 fresh set.
414 o Iterating over a hash causes a special optimization if you have not
416 obtained a lock (it is better to obtain a read (or write) lock
417 before iterating over a hash tied to Shareable, but we attempt this
418 optimization if you do not). The fetch/thaw operation is performed
419 when the first key is accessed. Subsequent key and and value
420 accesses are done without accessing shared memory. Doing an
421 assignment to the hash or fetching another value between key
422 accesses causes the hash to be replaced from shared memory. The
423 state of the iterator in this case is not defined by the Perl docu‐
424 mentation. Caveat Emptor.
425
427 Thanks to all those with comments or bug fixes, especially
428 Maurice Aubrey <maurice@hevanet.com>
430 Stephane Bortzmeyer <bortzmeyer@pasteur.fr>
431 Doug MacEachern <dougm@telebusiness.co.nz>
432 Robert Emmery <roberte@netscape.com>
433 Mohammed J. Kabir <kabir@intevo.com>
434 Terry Ewing <terry@intevo.com>
435 Tim Fries <timf@dicecorp.com>
436 Joe Thomas <jthomas@women.com>
437 Paul Makepeace <Paul.Makepeace@realprogrammers.com>
438 Raphael Manfredi <Raphael_Manfredi@pobox.com>
439 Lee Lindley <Lee.Lindley@bigfoot.com>
440 Dave Rolsky <autarch@urth.org>
441
443 Certainly; this is beta software. When you discover an anomaly, send an
444 email to me at bsugars@canoe.ca.
445
447 perl(1), perltie(1), Storable(3), shmget(2), ipcs(1), ipcrm(1) and
448 other SysV IPC man pages.
449perl v5.8.8 2000-07-20 IPC::Shareable(3)