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           IPC::Shareable::clean_up_protected;
33
34           # Ensure only one instance of a script can be run at any time
35
36           IPC::Shareable->singleton('UNIQUE SCRIPT LOCK STRING');
37
38           # Get the actual IPC::Shareable tied object
39
40           my $knot = tied(VARIABLE); # Dereference first if using a tied reference
41

DESCRIPTION

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

OPTIONS

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

METHODS

223   new
224       Instantiates and returns a reference to a hash backed by shared memory.
225
226           my $href = IPC::Shareable->new(key => "testing", create => 1);
227
228           $href=>{a} = 1;
229
230           # Call tied() on the dereferenced variable to access object methods
231           # and information
232
233           tied(%$href)->ipcs;
234
235       Parameters:
236
237       Hash, Optional: See the "OPTIONS" section for a list of all available
238       options.  Most often, you'll want to send in the key and create
239       options.
240
241       It is possible to get a reference to an array or scalar as well. Simply
242       send in either "var = > 'ARRAY'" or "var => 'SCALAR'" to do so.
243
244       Return: A reference to a hash (or array or scalar) which is backed by
245       shared memory.
246
247   singleton($glue, $warn)
248       Class method that ensures that only a single instance of a script can
249       be run at any given time.
250
251       Parameters:
252
253           $glue
254
255       Mandatory, String: The key/glue that identifies the shared memory
256       segment.
257
258           $warn
259
260       Optional, Bool: Send in a true value to have subsequent processes throw
261       a warning that there's been a shared memory violation and that it will
262       exit.
263
264       Default: false
265
266   ipcs
267       Returns the number of instantiated shared memory segments that
268       currently exist on the system. This isn't precise; it simply does a "wc
269       -l" line count on your system's "ipcs -m" call. It is guaranteed though
270       to produce reliable results.
271
272       Return: Integer
273
274   lock($flags)
275       Obtains a lock on the shared memory. $flags specifies the type of lock
276       to acquire.  If $flags is not specified, an exclusive read/write lock
277       is obtained.  Acceptable values for $flags are the same as for the
278       flock() system call.
279
280       Returns "true" on success, and "undef" on error. For non-blocking calls
281       (see below), the method returns 0 if it would have blocked.
282
283       Obtain an exclusive lock like this:
284
285               tied(%var)->lock(LOCK_EX); # same as default
286
287       Only one process can hold an exclusive lock on the shared memory at a
288       given time.
289
290       Obtain a shared (read) lock:
291
292               tied(%var)->lock(LOCK_SH);
293
294       Multiple processes can hold a shared (read) lock at a given time.  If a
295       process attempts to obtain an exclusive lock while one or more
296       processes hold shared locks, it will be blocked until they have all
297       finished.
298
299       Either of the locks may be specified as non-blocking:
300
301               tied(%var)->lock( LOCK_EX|LOCK_NB );
302               tied(%var)->lock( LOCK_SH|LOCK_NB );
303
304       A non-blocking lock request will return 0 if it would have had to wait
305       to obtain the lock.
306
307       Note that these locks are advisory (just like flock), meaning that all
308       cooperating processes must coordinate their accesses to shared memory
309       using these calls in order for locking to work.  See the flock() call
310       for details.
311
312       Locks are inherited through forks, which means that two processes
313       actually can possess an exclusive lock at the same time. Don't do that.
314
315       The constants "LOCK_EX", "LOCK_SH", "LOCK_NB", and "LOCK_UN" are
316       available for import using any of the following export tags:
317
318               use IPC::Shareable qw(:lock);
319               use IPC::Shareable qw(:flock);
320               use IPC::Shareable qw(:all);
321
322       Or, just use the flock constants available in the Fcntl module.
323
324       See "LOCKING" for further details.
325
326   unlock
327       Removes a lock. Takes no parameters, returns "true" on success.
328
329       This is equivalent of calling shlock(LOCK_UN).
330
331       See "LOCKING" for further details.
332
333   seg
334       Called on either the tied variable or the tie object, returns the
335       shared memory segment object currently in use.
336
337   sem
338       Called on either the tied variable or the tie object, returns the
339       semaphore object related to the memory segment currently in use.
340
341   attributes
342       Retrieves the list of attributes that drive the IPC::Shareable object.
343
344       Parameters:
345
346           $attribute
347
348       Optional, String: The name of the attribute. If sent in, we'll return
349       the value of this specific attribute. Returns "undef" if the attribute
350       isn't found.
351
352       Attributes are the "OPTIONS" that were used to create the object.
353
354       Returns: A hash reference of all attributes if $attributes isn't sent
355       in, the value of the specific attribute if it is.
356
357   global_register
358       Returns a hash reference of hashes of all in-use shared memory segments
359       across all processes. The key is the memory segment ID, and the value
360       is the segment and semaphore objects.
361
362   process_register
363       Returns a hash reference of hashes of all in-use shared memory segments
364       created by the calling process. The key is the memory segment ID, and
365       the value is the segment and semaphore objects.
366

LOCKING

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

DESTRUCTION

418       perl(1) will destroy the object underlying a tied variable when then
419       tied variable goes out of scope.  Unfortunately for IPC::Shareable,
420       this may not be desirable: other processes may still need a handle on
421       the relevant shared memory segment.
422
423       IPC::Shareable therefore provides several options to control the timing
424       of removal of shared memory segments.
425
426   destroy Option
427       As described in "OPTIONS", specifying the destroy option when tie()ing
428       a variable coerces IPC::Shareable to remove the underlying shared
429       memory segment when the process calling tie() exits gracefully.
430
431       NOTE: The destruction is handled in an "END" block. Only those memory
432       segments that are tied to the current process will be removed.
433
434       NOTE: If the segment was created with its "protected" attribute set, it
435       will not be removed in the "END" block, even if "destroy" is set.
436
437   remove
438           tied($var)->remove;
439
440           # or
441
442           $knot->remove;
443
444       Calling remove() on the object underlying a tie()d variable removes the
445       associated shared memory segments.  The segment is removed irrespective
446       of whether it has the destroy option set or not and irrespective of
447       whether the calling process created the segment.
448
449   clean_up
450           IPC::Shareable->clean_up;
451
452           # or
453
454           tied($var)->clean_up;
455
456           # or
457
458           $knot->clean_up;
459
460       This is a class method that provokes IPC::Shareable to remove all
461       shared memory segments created by the process.  Segments not created by
462       the calling process are not removed.
463
464       This method will not clean up segments created with the "protected"
465       option.
466
467   clean_up_all
468           IPC::Shareable->clean_up_all;
469
470           # or
471
472           tied($var)->clean_up_all;
473
474           # or
475
476           $knot->clean_up_all
477
478       This is a class method that provokes IPC::Shareable to remove all
479       shared memory segments encountered by the process.  Segments are
480       removed even if they were not created by the calling process.
481
482       This method will not clean up segments created with the "protected"
483       option.
484
485   clean_up_protected($protect_key)
486       If a segment is created with the "protected" option, it, nor its
487       children will be removed during calls of clean_up() or clean_up_all().
488
489       When setting "protected", you specified a lock key integer. When
490       calling this method, you must send that integer in as a parameter so we
491       know which segments to clean up.
492
493           my $protect_key = 93432;
494
495           IPC::Shareable->clean_up_protected($protect_key);
496
497           # or
498
499           tied($var)->clean_up_protected($protect_key;
500
501           # or
502
503           $knot->clean_up_protected($protect_key)
504
505       Parameters:
506
507           $protect_key
508
509       Mandatory, Integer: The integer protect key you assigned wit the
510       "protected" option
511

RETURN VALUES

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

AUTHOR

517       Benjamin Sugars <bsugars@canoe.ca>
518

MAINTAINED BY

520       Steve Bertrand <steveb@cpan.org>
521

NOTES

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

CREDITS

608       Thanks to all those with comments or bug fixes, especially
609
610           Maurice Aubrey      <maurice@hevanet.com>
611           Stephane Bortzmeyer <bortzmeyer@pasteur.fr>
612           Doug MacEachern     <dougm@telebusiness.co.nz>
613           Robert Emmery       <roberte@netscape.com>
614           Mohammed J. Kabir   <kabir@intevo.com>
615           Terry Ewing         <terry@intevo.com>
616           Tim Fries           <timf@dicecorp.com>
617           Joe Thomas          <jthomas@women.com>
618           Paul Makepeace      <Paul.Makepeace@realprogrammers.com>
619           Raphael Manfredi    <Raphael_Manfredi@pobox.com>
620           Lee Lindley         <Lee.Lindley@bigfoot.com>
621           Dave Rolsky         <autarch@urth.org>
622           Steve Bertrand      <steveb@cpan.org>
623

SEE ALSO

625       perltie, Storable, "shmget", "ipcs", "ipcrm" and other SysV IPC manual
626       pages.
627
628
629
630perl v5.38.0                      2023-07-20                 IPC::Shareable(3)
Impressum