IPC::Shareable(3pm)

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

NAME

6       IPC::Shareable - Use shared memory backed variables across processes
7

SYNOPSIS

9           use IPC::Shareable qw(:lock);
10
11           my $href = IPC::Shareable->new(%options);
12
13           # ...or
14
15           tie SCALAR, 'IPC::Shareable', OPTIONS;
16           tie ARRAY,  'IPC::Shareable', OPTIONS;
17           tie HASH,   'IPC::Shareable', OPTIONS;
18
19           (tied VARIABLE)->lock;
20           (tied VARIABLE)->unlock;
21
22           (tied VARIABLE)->lock(LOCK_SH|LOCK_NB)
23               or print "Resource unavailable\n";
24
25           my $segment   = (tied VARIABLE)->seg;
26           my $semaphore = (tied VARIABLE)->sem;
27
28           (tied VARIABLE)->remove;
29
30           IPC::Shareable->clean_up;
31           IPC::Shareable->clean_up_all;
32
33           # Ensure only one instance of a script can be run at any time
34
35           IPC::Shareable->singleton('UNIQUE SCRIPT LOCK STRING');
36

DESCRIPTION

38       IPC::Shareable allows you to tie a variable to shared memory making it
39       easy to share the contents of that variable with other Perl processes
40       and scripts.
41
42       Scalars, arrays, hashes and even objects can be tied. The variable
43       being tied may contain arbitrarily complex data structures - including
44       references to arrays, hashes of hashes, etc.
45
46       The association between variables in distinct processes is provided by
47       GLUE (aka "key").  This is any arbitrary string or integer that serves
48       as a common identifier for data across process space.  Hence the
49       statement:
50
51           tie my $scalar, 'IPC::Shareable', { key => 'GLUE STRING', create => 1 };
52
53       ...in program one and the statement
54
55           tie my $variable, 'IPC::Shareable', { key => 'GLUE STRING' };
56
57       ...in program two will create and bind $scalar the shared memory in
58       program one and bind it to $variable in program two.
59
60       There is no pre-set limit to the number of processes that can bind to
61       data; nor is there a pre-set limit to the complexity of the underlying
62       data of the tied variables.  The amount of data that can be shared
63       within a single bound variable is limited by the system's maximum size
64       for a shared memory segment (the exact value is system-dependent).
65
66       The bound data structures are all linearized (using Raphael Manfredi's
67       Storable module or optionally JSON) before being slurped into shared
68       memory.  Upon retrieval, the original format of the data structure is
69       recovered.  Semaphore flags can be used for locking data between
70       competing processes.
71

OPTIONS

73       Options are specified by passing a reference to a hash as the third
74       argument to the "tie()" function that enchants a variable.
75
76       The following fields are recognized in the options hash:
77
78   key
79       key is the GLUE that is a direct reference to the shared memory segment
80       that's to be tied to the variable.
81
82       If this option is missing, we'll default to using "IPC_PRIVATE". This
83       default key will not allow sharing of the variable between processes.
84
85       Default: IPC_PRIVATE
86
87   create
88       create is used to control whether the process creates a new shared
89       memory segment or not.  If create is set to a true value,
90       IPC::Shareable will create a new binding associated with GLUE as
91       needed.  If create is false, IPC::Shareable will not attempt to create
92       a new shared memory segment associated with GLUE.  In this case, a
93       shared memory segment associated with GLUE must already exist or we'll
94       "croak()".
95
96       Defult: false
97
98   exclusive
99       If exclusive field is set to a true value, we will "croak()" if the
100       data binding associated with GLUE already exists.  If set to a false
101       value, calls to "tie()" will succeed even if a shared memory segment
102       associated with GLUE already exists.
103
104       See "graceful" for a silent, non-exception exit if a second process
105       attempts to obtain an in-use "exclusive" segment.
106
107       Default: false
108
109   graceful
110       If exclusive is set to a true value, we normally "croak()" if a second
111       process attempts to obtain the same shared memory segment. Set graceful
112       to true and we'll "exit" silently and gracefully. This option does
113       nothing if "exclusive" isn't set.
114
115       Useful for ensuring only a single process is running at a time.
116
117       Default: false
118
119   warn
120       When set to a true value, graceful will output a warning if there are
121       process collisions.
122
123       Default: false
124
125   mode
126       The mode argument is an octal number specifying the access permissions
127       when a new data binding is being created.  These access permission are
128       the same as file access permissions in that 0666 is world readable,
129       0600 is readable only by the effective UID of the process creating the
130       shared variable, etc.
131
132       Default: 0666 (world read and writeable)
133
134   size
135       This field may be used to specify the size of the shared memory segment
136       allocated.
137
138       The maximum size we allow by default is ~1GB. See the "limit" option to
139       override this default.
140
141       Default: "IPC::Shareable::SHM_BUFSIZ()" (ie. 65536)
142
143   limit
144       This field will allow you to set a segment size larger than the default
145       maximum which is 1,073,741,824 bytes (approximately 1 GB). If set, we
146       will "croak()" if a size specified is larger than the maximum. If it's
147       set to a false value, we'll "croak()" if you send in a size larger than
148       the total system RAM.
149
150       Default: true
151
152   destroy
153       If set to a true value, the shared memory segment underlying the data
154       binding will be removed when the process that initialized the shared
155       memory segment exits (gracefully)[1].
156
157       Only those memory segments that were created by the current process
158       will be removed.
159
160       Use this option with care. In particular you should not use this option
161       in a program that will fork after binding the data.  On the other hand,
162       shared memory is a finite resource and should be released if it is not
163       needed.
164
165       Default: false
166
167   tidy
168       For long running processes, set this to a true value to clean up
169       unneeded segments from nested data structures. Comes with a slight
170       performance hit.
171
172       Default: false
173
174   serializer
175       By default, we use Storable as the data serializer when writing to or
176       reading from the shared memory segments we create. For cross-platform
177       and cross-language purposes, you can optionally use JSON for this task.
178
179       Send in either "json" or "storable" as the value to use the respective
180       serializer.
181
182       Default: storable
183
184   Default Option Values
185       Default values for options are:
186
187           key         => IPC_PRIVATE,
188           create      => 0,
189           exclusive   => 0,
190           mode        => 0,
191           size        => IPC::Shareable::SHM_BUFSIZ(),
192           limit       => 1,
193           destroy     => 0,
194           graceful    => 0,
195           warn        => 0,
196           tidy        => 0,
197           serializer  => 'storable',
198

METHODS

200   new
201       Instantiates and returns a reference to a hash backed by shared memory.
202
203       Parameters:
204
205       Hash, Optional: See the "OPTIONS" section for a list of all available
206       options.  Most often, you'll want to send in the key, create and
207       destroy options.
208
209       It is possible to get a reference to an array or scalar as well. Simply
210       send in either "var = > 'ARRAY'" or "var => 'SCALAR'" to do so.
211
212       Return: A reference to a hash (or array or scalar) which is backed by
213       shared memory.
214
215   singleton($glue, $warn)
216       Class method that ensures that only a single instance of a script can
217       be run at any given time.
218
219       Parameters:
220
221           $glue
222
223       Mandatory, String: The key/glue that identifies the shared memory
224       segment.
225
226           $warn
227
228       Optional, Bool: Send in a true value to have subsequent processes throw
229       a warning that there's been a shared memory violation and that it will
230       exit.
231
232       Default: false
233
234   ipcs
235       Returns the number of instantiated shared memory segments that
236       currently exist on the system.
237
238       Return: Integer
239
240   spawn(%opts)
241       Spawns a forked process running in the background that holds the shared
242       memory segments backing your variable open.
243
244       Parameters:
245
246       Paremters are sent in as a hash.
247
248           key => $glue
249
250       Mandatory, String/Integer: The glue that you will be accessing your
251       data as.
252
253           mode => 0666
254
255       Optional, Integer: The read/write permissions on the variable. Defaults
256       to 0666.
257
258       Example:
259
260           use IPC::Shareable;
261
262           # The following line sets things up and returns
263
264           IPC::Shareable->spawn(key => 'GLUE STRING');
265
266       Now, either within the same script, or any other script on the system,
267       your data will be available at the key/glue "GLUE STRING". Call
268       unspawn() to remove it.
269
270   unspawn($key, $destroy)
271       This method will kill off the background process created with spawn().
272
273       Parameters:
274
275           $key
276
277       Mandatory, String/Integer: The glue (aka key) used in the call to
278       "spawn()".
279
280           $destroy
281
282       Optional, Bool. If set to a true value, we will remove all semaphores
283       and memory segments related to your data, thus removing the data in its
284       entirety. If not set to a true value, we'll leave the memory segments
285       in place, and you'll be able to re-attach to the data at any time.
286       Defaults to false (0).
287
288   lock($flags)
289       Obtains a lock on the shared memory. $flags specifies the type of lock
290       to acquire.  If $flags is not specified, an exclusive read/write lock
291       is obtained.  Acceptable values for $flags are the same as for the
292       "flock()" system call.
293
294       Returns "true" on success, and "undef" on error.  For non-blocking
295       calls (see below), the method returns 0 if it would have blocked.
296
297       Obtain an exclusive lock like this:
298
299               tied(%var)->lock(LOCK_EX); # same as default
300
301       Only one process can hold an exclusive lock on the shared memory at a
302       given time.
303
304       Obtain a shared (read) lock:
305
306               tied(%var)->lock(LOCK_SH);
307
308       Multiple processes can hold a shared (read) lock at a given time.  If a
309       process attempts to obtain an exclusive lock while one or more
310       processes hold shared locks, it will be blocked until they have all
311       finished.
312
313       Either of the locks may be specified as non-blocking:
314
315               tied(%var)->lock( LOCK_EX|LOCK_NB );
316               tied(%var)->lock( LOCK_SH|LOCK_NB );
317
318       A non-blocking lock request will return 0 if it would have had to wait
319       to obtain the lock.
320
321       Note that these locks are advisory (just like flock), meaning that all
322       cooperating processes must coordinate their accesses to shared memory
323       using these calls in order for locking to work.  See the "flock()" call
324       for details.
325
326       Locks are inherited through forks, which means that two processes
327       actually can possess an exclusive lock at the same time.  Don't do
328       that.
329
330       The constants "LOCK_EX", "LOCK_SH", "LOCK_NB", and "LOCK_UN" are
331       available for import using any of the following export tags:
332
333               use IPC::Shareable qw(:lock);
334               use IPC::Shareable qw(:flock);
335               use IPC::Shareable qw(:all);
336
337       Or, just use the flock constants available in the Fcntl module.
338
339       See "LOCKING" for further details.
340
341   unlock
342       Removes a lock. Takes no parameters, returns "true" on success.
343
344       This is equivalent of calling "shlock(LOCK_UN)".
345
346       See "LOCKING" for further details.
347
348   seg
349       Called on either the tied variable or the tie object, returns the
350       shared memory segment object currently in use.
351
352   sem
353       Called on either the tied variable or the tie object, returns the
354       semaphore object related to the memory segment currently in use.
355
356   attributes
357       Retrieves the list of attributes that drive the IPC::Shareable object.
358
359       Parameters:
360
361           $attribute
362
363       Optional, String: The name of the attribute. If sent in, we'll return
364       the value of this specific attribute. Returns "undef" if the attribute
365       isn't found.
366
367       Returns: A hash reference of all attributes if $attributes isn't sent
368       in, the value of the specific attribute if it is.
369
370   global_register
371       Returns a hash reference of hashes of all in-use shared memory segments
372       across all processes. The key is the memory segment ID, and the value
373       is the segment and semaphore objects.
374
375   process_register
376       Returns a hash reference of hashes of all in-use shared memory segments
377       created by the calling process. The key is the memory segment ID, and
378       the value is the segment and semaphore objects.
379

LOCKING

381       IPC::Shareable provides methods to implement application-level advisory
382       locking of the shared data structures.  These methods are called
383       "shlock()" and "shunlock()".  To use them you must first get the object
384       underlying the tied variable, either by saving the return value of the
385       original call to "tie()" or by using the built-in "tied()" function.
386
387       To lock and subsequently unlock a variable, do this:
388
389           my $knot = tie my %hash, 'IPC::Shareable', { %options };
390
391           $knot->lock;
392           $hash{a} = 'foo';
393           $knot->unlock;
394
395       or equivalently, if you've decided to throw away the return of "tie()":
396
397           tie my %hash, 'IPC::Shareable', { %options };
398
399           tied(%hash)->lock;
400           $hash{a} = 'foo';
401           tied(%hash)->unlock;
402
403       This will place an exclusive lock on the data of $scalar.  You can also
404       get shared locks or attempt to get a lock without blocking.
405
406       IPC::Shareable makes the constants "LOCK_EX", "LOCK_SH", "LOCK_UN", and
407       "LOCK_NB" exportable to your address space with the export tags
408       ":lock", ":flock", or ":all".  The values should be the same as the
409       standard "flock" option arguments.
410
411           if (tied(%hash)->lock(LOCK_SH|LOCK_NB)){
412               print "The value is $hash{a}\n";
413               tied(%hash)->unlock;
414           } else {
415               print "Another process has an exlusive lock.\n";
416           }
417
418       If no argument is provided to "lock", it defaults to "LOCK_EX".
419
420       There are some pitfalls regarding locking and signals about which you
421       should make yourself aware; these are discussed in "NOTES".
422
423       Note that in the background, we perform lock optimization when reading
424       and writing to the shared storage even if the advisory locks aren't
425       being used.
426
427       Using the advisory locks can speed up processes that are doing several
428       writes/ reads at the same time.
429

REFERENCES

431       Although references can reside within a shared data structure, the tied
432       variable can not be a reference itself.
433

DESTRUCTION

435       perl(1) will destroy the object underlying a tied variable when then
436       tied variable goes out of scope.  Unfortunately for IPC::Shareable,
437       this may not be desirable: other processes may still need a handle on
438       the relevant shared memory segment.
439
440       IPC::Shareable therefore provides several options to control the timing
441       of removal of shared memory segments.
442
443   destroy Option
444       As described in "OPTIONS", specifying the destroy option when
445       "tie()"ing a variable coerces IPC::Shareable to remove the underlying
446       shared memory segment when the process calling "tie()" exits
447       gracefully.
448
449       NOTE: The destruction is handled in an "END" block. Only those memory
450       segments that are tied to the current process will be removed.
451
452   remove
453           tied($var)->remove;
454
455           # or
456
457           $knot->remove;
458
459       Calling "remove()" on the object underlying a "tie()"d variable removes
460       the associated shared memory segments.  The segment is removed
461       irrespective of whether it has the destroy option set or not and
462       irrespective of whether the calling process created the segment.
463
464   clean_up
465           IPC::Shareable->clean_up;
466
467           # or
468
469           tied($var)->clean_up;
470
471           # or
472
473           $knot->clean_up;
474
475       This is a class method that provokes IPC::Shareable to remove all
476       shared memory segments created by the process.  Segments not created by
477       the calling process are not removed.
478
479   clean_up_all
480           IPC::Shareable->clean_up_all;
481
482           # or
483
484           tied($var)->clean_up_all;
485
486           # or
487
488           $knot->clean_up_all
489
490       This is a class method that provokes IPC::Shareable to remove all
491       shared memory segments encountered by the process.  Segments are
492       removed even if they were not created by the calling process.
493

RETURN VALUES

495       Calls to "tie()" that try to implement IPC::Shareable will return an
496       instance of "IPC::Shareable" on success, and "undef" otherwise.
497

AUTHOR

499       Benjamin Sugars <bsugars@canoe.ca>
500

MAINTAINED BY

502       Steve Bertrand <steveb@cpan.org>
503

NOTES

505   Footnotes from the above sections
506       1.  If the process has been smoked by an untrapped signal, the binding
507           will remain in shared memory.  If you're cautious, you might try
508
509            $SIG{INT} = \&catch_int;
510            sub catch_int {
511                die;
512            }
513            ...
514            tie $variable, IPC::Shareable, { key => 'GLUE', create => 1, 'destroy' => 1 };
515
516           which will at least clean up after your user hits CTRL-C because
517           IPC::Shareable's END method will be called.  Or, maybe you'd like
518           to leave the binding in shared memory, so subsequent process can
519           recover the data...
520
521   General Notes
522       o   When using "lock()" to lock a variable, be careful to guard against
523           signals.  Under normal circumstances, "IPC::Shareable"'s "END"
524           method unlocks any locked variables when the process exits.
525           However, if an untrapped signal is received while a process holds
526           an exclusive lock, "DESTROY" will not be called and the lock may be
527           maintained even though the process has exited.  If this scares you,
528           you might be better off implementing your own locking methods.
529
530           One advantage of using "flock" on some known file instead of the
531           locking implemented with semaphores in "IPC::Shareable" is that
532           when a process dies, it automatically releases any locks.  This
533           only happens with "IPC::Shareable" if the process dies gracefully.
534
535           The alternative is to attempt to account for every possible
536           calamitous ending for your process (robust signal handling in Perl
537           is a source of much debate, though it usually works just fine) or
538           to become familiar with your system's tools for removing shared
539           memory and semaphores.  This concern should be balanced against the
540           significant performance improvements you can gain for larger data
541           structures by using the locking mechanism implemented in
542           IPC::Shareable.
543
544       o   There is a program called "ipcs"(1/8) (and "ipcrm"(1/8)) that is
545           available on at least Solaris and Linux that might be useful for
546           cleaning moribund shared memory segments or semaphore sets produced
547           by bugs in either IPC::Shareable or applications using it.
548
549           Examples:
550
551               # List all semaphores and memory segments in use on the system
552
553               ipcs -a
554
555               # List all memory segments and semaphores along with each one's associated process ID
556
557               ipcs -ap
558
559               # List just the shared memory segments
560
561               ipcs -m
562
563               # List the details of an individual memory segment
564
565               ipcs -i 12345678
566
567               # Remove *all* semaphores and memory segments
568
569               ipcrm -a
570
571       o   This version of IPC::Shareable does not understand the format of
572           shared memory segments created by versions prior to 0.60.  If you
573           try to tie to such segments, you will get an error.  The only work
574           around is to clear the shared memory segments and start with a
575           fresh set.
576
577       o   Iterating over a hash causes a special optimization if you have not
578           obtained a lock (it is better to obtain a read (or write) lock
579           before iterating over a hash tied to IPC::Shareable, but we attempt
580           this optimization if you do not).
581
582           The "fetch"/"thaw" operation is performed when the first key is
583           accessed.  Subsequent key and and value accesses are done without
584           accessing shared memory.  Doing an assignment to the hash or
585           fetching another value between key accesses causes the hash to be
586           replaced from shared memory.  The state of the iterator in this
587           case is not defined by the Perl documentation.  Caveat Emptor.
588

CREDITS

590       Thanks to all those with comments or bug fixes, especially
591
592           Maurice Aubrey      <maurice@hevanet.com>
593           Stephane Bortzmeyer <bortzmeyer@pasteur.fr>
594           Doug MacEachern     <dougm@telebusiness.co.nz>
595           Robert Emmery       <roberte@netscape.com>
596           Mohammed J. Kabir   <kabir@intevo.com>
597           Terry Ewing         <terry@intevo.com>
598           Tim Fries           <timf@dicecorp.com>
599           Joe Thomas          <jthomas@women.com>
600           Paul Makepeace      <Paul.Makepeace@realprogrammers.com>
601           Raphael Manfredi    <Raphael_Manfredi@pobox.com>
602           Lee Lindley         <Lee.Lindley@bigfoot.com>
603           Dave Rolsky         <autarch@urth.org>
604           Steve Bertrand      <steveb@cpan.org>
605