1IPC::Shareable(3)     User Contributed Perl Documentation    IPC::Shareable(3)
2
3
4

NAME

6       IPC::Shareable - share Perl variables between processes
7

SYNOPSIS

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
14        (tied VARIABLE)->shlock;
15        (tied VARIABLE)->shunlock;
16
17        (tied VARIABLE)->shlock(LOCK_SH|LOCK_NB)
18               or print "resource unavailable\n";
19
20        (tied VARIABLE)->remove;
21
22        IPC::Shareable->clean_up;
23        IPC::Shareable->clean_up_all;
24

CONVENTIONS

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

DESCRIPTION

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
36       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
41        tie $scalar, 'IPC::Shareable', 'data';
42
43       in program one and the statement
44
45        tie $variable, 'IPC::Shareable', 'data';
46
47       in program two will bind $scalar in program one and $variable in
48       program two.
49
50       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
56       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

OPTIONS

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
69        tie $variable, 'IPC::Shareable', 'data', \%options;
70
71       is equivalent to
72
73        tie $variable, 'IPC::Shareable', { key => 'data', ... };
74
75       Boolean option values can be specified using a value that evaluates to
76       either true or false in the Perl sense.
77
78       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
85       The following fields are recognized in the options hash.
86
87       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
92           The default value is IPC_PRIVATE, meaning that your variables
93           cannot be shared with other processes.
94
95       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
105       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
112       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
120       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
129       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
133       Default values for options are
134
135        key       => IPC_PRIVATE,
136        create    => 0,
137        exclusive => 0,
138        destroy   => 0,
139        mode      => 0,
140        size      => IPC::Shareable::SHM_BUFSIZ(),
141

LOCKING

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
149       To lock a variable, do this:
150
151        $knot = tie $sv, 'IPC::Shareable', $glue, { %options };
152        ...
153        $knot->shlock;
154
155       or equivalently
156
157        tie($scalar, 'IPC::Shareable', $glue, { %options });
158        (tied $scalar)->shlock;
159
160       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
167        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
174       If no argument is provided to "shlock", it defaults to LOCK_EX.  To
175       unlock a variable do this:
176
177        $knot->shunlock;
178
179       or
180
181        (tied $scalar)->shunlock;
182
183       or
184
185        $knot->shlock(LOCK_UN);        # Same as calling shunlock
186
187       There are some pitfalls regarding locking and signals about which you
188       should make yourself aware; these are discussed in "NOTES".
189
190       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
201       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
205       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

REFERENCES

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
217       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
222       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

OBJECTS

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

DESTRUCTION

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
242       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
249       remove()
250            (tied $var)->remove;
251
252           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
257       clean_up()
258            IPC::Shareable->clean_up;
259
260           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
264       clean_up_all()
265            IPC::Shareable->clean_up_all;
266
267           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

EXAMPLES

272       In a file called server:
273
274        #!/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
306       In a file called client
307
308        #!/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
328       And here is the output (the sleep commands in the command line prevent
329       the output from being interrupted by shell prompts):
330
331        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

RETURN VALUES

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

AUTHOR

346       Benjamin Sugars <bsugars@canoe.ca>
347

NOTES

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
355       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
360       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
363            $SIG{INT} = \&catch_int;
364            sub catch_int {
365                die;
366            }
367            ...
368            tie $variable, IPC::Shareable, 'data', { 'destroy' => 'Yes!' };
369
370           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
375       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
381   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
390           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
403       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
408       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
414       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

CREDITS

426       Thanks to all those with comments or bug fixes, especially
427
428        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

BUGS

442       Certainly; this is beta software. When you discover an anomaly, send an
443       email to me at bsugars@canoe.ca.
444

SEE ALSO

446       perl(1), perltie(1), Storable(3), shmget(2), ipcs(1), ipcrm(1) and
447       other SysV IPC man pages.
448
449
450
451perl v5.32.1                      2021-01-27                 IPC::Shareable(3)
Impressum