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
39 statement
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
48 program 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
60 processes.
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;
66 IPC::Shareable will then look at the field named key in this hash for
67 the value 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
93 cannot 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
114 permissions when a new data binding is being created. These access
115 permission 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
125 binding 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
193 performed. 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
220 collision.
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
246 gracefully. 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
254 irrespective of whether it has the destroy option set or not and
255 irrespective 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
262 created 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
351 characters are used. These characters are turned into integers by
352 unpack()ing them. If GLUE is less than 4 characters, it is space
353 padded.
354 2. IPC::Shareable provides no pre-set limits, but the system does.
356 Namely, there are limits on the number of shared memory segments
357 that can be allocated and the total amount of memory usable by
358 shared memory.
359 3. If the process has been smoked by an untrapped signal, the binding
361 will remain in shared memory. If you're cautious, you might try
362 $SIG{INT} = \&catch_int;
364 sub catch_int {
365 die;
366 }
367 ...
368 tie $variable, IPC::Shareable, 'data', { 'destroy' => 'Yes!' };
369 which will at least clean up after your user hits CTRL-C because
371 IPC::Shareable's END method will be called. Or, maybe you'd like
372 to leave the binding in shared memory, so subsequent process can
373 recover the data...
374 4. This behaviour is markedly different from previous versions of
376 IPC::Shareable. Older versions would sometimes tie() referenced
377 thingies, and sometimes not. The new approach is more reliable (I
378 think) and predictable (certainly) but uses more shared memory
379 segments.
380 General Notes
382 o When using shlock() to lock a variable, be careful to guard against
383 signals. Under normal circumstances, IPC::Shareable's END method
384 unlocks any locked variables when the process exits. However, if
385 an untrapped signal is received while a process holds an exclusive
386 lock, DESTROY will not be called and the lock may be maintained
387 even though the process has exited. If this scares you, you might
388 be better off implementing your own locking methods.
389 One advantage of using "flock" on some known file instead of the
391 locking implemented with semaphores in IPC::Shareable is that when
392 a process dies, it automatically releases any locks. This only
393 happens with IPC::Shareable if the process dies gracefully. The
394 alternative is to attempt to account for every possible calamitous
395 ending for your process (robust signal handling in Perl is a source
396 of much debate, though it usually works just fine) or to become
397 familiar with your system's tools for removing shared memory and
398 semaphores. This concern should be balanced against the
399 significant performance improvements you can gain for larger data
400 structures by using the locking mechanism implemented in
401 IPC::Shareable.
402 o There is a program called ipcs(1/8) (and ipcrm(1/8)) that is
404 available on at least Solaris and Linux that might be useful for
405 cleaning moribund shared memory segments or semaphore sets produced
406 by bugs in either IPC::Shareable or applications using it.
407 o This version of IPC::Shareable does not understand the format of
409 shared memory segments created by versions prior to 0.60. If you
410 try to tie to such segments, you will get an error. The only work
411 around is to clear the shared memory segments and start with a
412 fresh set.
413 o Iterating over a hash causes a special optimization if you have not
415 obtained a lock (it is better to obtain a read (or write) lock
416 before iterating over a hash tied to Shareable, but we attempt this
417 optimization if you do not). The fetch/thaw operation is performed
418 when the first key is accessed. Subsequent key and and value
419 accesses are done without accessing shared memory. Doing an
420 assignment to the hash or fetching another value between key
421 accesses causes the hash to be replaced from shared memory. The
422 state of the iterator in this case is not defined by the Perl
423 documentation. Caveat Emptor.
424
426 Thanks to all those with comments or bug fixes, especially
427 Maurice Aubrey <maurice@hevanet.com>
429 Stephane Bortzmeyer <bortzmeyer@pasteur.fr>
430 Doug MacEachern <dougm@telebusiness.co.nz>
431 Robert Emmery <roberte@netscape.com>
432 Mohammed J. Kabir <kabir@intevo.com>
433 Terry Ewing <terry@intevo.com>
434 Tim Fries <timf@dicecorp.com>
435 Joe Thomas <jthomas@women.com>
436 Paul Makepeace <Paul.Makepeace@realprogrammers.com>
437 Raphael Manfredi <Raphael_Manfredi@pobox.com>
438 Lee Lindley <Lee.Lindley@bigfoot.com>
439 Dave Rolsky <autarch@urth.org>
440
442 Certainly; this is beta software. When you discover an anomaly, send an
443 email to me at bsugars@canoe.ca.
444
446 perl(1), perltie(1), Storable(3), shmget(2), ipcs(1), ipcrm(1) and
447 other SysV IPC man pages.
448perl v5.32.1 2021-01-27 IPC::Shareable(3)