1IPC::Shareable(3) User Contributed Perl Documentation IPC::Shareable(3)
2
6 IPC::Shareable - Use shared memory backed variables across processes
7
9 use IPC::Shareable qw(:lock);
10 my $href = IPC::Shareable->new(%options);
12 # ...or
14 tie SCALAR, 'IPC::Shareable', OPTIONS;
16 tie ARRAY, 'IPC::Shareable', OPTIONS;
17 tie HASH, 'IPC::Shareable', OPTIONS;
18 tied(VARIABLE)->lock;
20 tied(VARIABLE)->unlock;
21 tied(VARIABLE)->lock(LOCK_SH|LOCK_NB)
23 or print "Resource unavailable\n";
24 my $segment = tied(VARIABLE)->seg;
26 my $semaphore = tied(VARIABLE)->sem;
27 tied(VARIABLE)->remove;
29 IPC::Shareable::clean_up;
31 IPC::Shareable::clean_up_all;
32 IPC::Shareable::clean_up_protected;
33 # Ensure only one instance of a script can be run at any time
35 IPC::Shareable->singleton('UNIQUE SCRIPT LOCK STRING');
37 # Get the actual IPC::Shareable tied object
39 my $knot = tied(VARIABLE); # Dereference first if using a tied reference
41
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 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 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 tie my $scalar, 'IPC::Shareable', { key => 'GLUE STRING', create => 1 };
57 ...in program one and the statement
59 tie my $variable, 'IPC::Shareable', { key => 'GLUE STRING' };
61 ...in program two will create and bind $scalar the shared memory in
63 program one and bind it to $variable in program two.
64 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 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
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 The following fields are recognized in the options hash:
82 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 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 Default: IPC_PRIVATE
91 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 Defult: false
102 exclusive
104 If exclusive field is set to a true value, we will "croak()" if the
105 data binding associated with GLUE already exists. If set to a false
106 value, calls to "tie()" will succeed even if a shared memory segment
107 associated with GLUE already exists.
108 See "graceful" for a silent, non-exception exit if a second process
110 attempts to obtain an in-use "exclusive" segment.
111 Default: false
113 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 Useful for ensuring only a single process is running at a time.
121 Default: false
123 warn
125 When set to a true value, graceful will output a warning if there are
126 process collisions.
127 Default: false
129 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 Default: 0666 (world read and writeable)
138 size
140 This field may be used to specify the size of the shared memory segment
141 allocated.
142 The maximum size we allow by default is ~1GB. See the "limit" option to
144 override this default.
145 Default: "IPC::Shareable::SHM_BUFSIZ()" (ie. 65536)
147 protected
149 If set, the "clean_up()" and "clean_up_all()" routines will not remove
150 the segments or semaphores related to the tied object.
151 Set this to a specific integer so we can pass the value to any child
153 objects created under the main one.
154 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 Default: 0
161 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 Default: true
170 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 Only those memory segments that were created by the current process
177 will be removed.
178 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 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 Default: false
188 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 Default: false
195 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 Send in either "json" or "storable" as the value to use the respective
202 serializer.
203 Default: storable
205 Default Option Values
207 Default values for options are:
208 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
223 new
224 Instantiates and returns a reference to a hash backed by shared memory.
225 my $href = IPC::Shareable->new(key => "testing", create => 1);
227 $href=>{a} = 1;
229 # Call tied() on the dereferenced variable to access object methods
231 # and information
232 tied(%$href)->ipcs;
234 Parameters:
236 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 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 Return: A reference to a hash (or array or scalar) which is backed by
245 shared memory.
246 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 Parameters:
252 $glue
254 Mandatory, String: The key/glue that identifies the shared memory
256 segment.
257 $warn
259 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 Default: false
265 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 Return: Integer
273 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 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 Obtain an exclusive lock like this:
284 tied(%var)->lock(LOCK_EX); # same as default
286 Only one process can hold an exclusive lock on the shared memory at a
288 given time.
289 Obtain a shared (read) lock:
291 tied(%var)->lock(LOCK_SH);
293 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 Either of the locks may be specified as non-blocking:
300 tied(%var)->lock( LOCK_EX|LOCK_NB );
302 tied(%var)->lock( LOCK_SH|LOCK_NB );
303 A non-blocking lock request will return 0 if it would have had to wait
305 to obtain the lock.
306 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 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 The constants "LOCK_EX", "LOCK_SH", "LOCK_NB", and "LOCK_UN" are
316 available for import using any of the following export tags:
317 use IPC::Shareable qw(:lock);
319 use IPC::Shareable qw(:flock);
320 use IPC::Shareable qw(:all);
321 Or, just use the flock constants available in the Fcntl module.
323 See "LOCKING" for further details.
325 unlock
327 Removes a lock. Takes no parameters, returns "true" on success.
328 This is equivalent of calling "shlock(LOCK_UN)".
330 See "LOCKING" for further details.
332 seg
334 Called on either the tied variable or the tie object, returns the
335 shared memory segment object currently in use.
336 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 attributes
342 Retrieves the list of attributes that drive the IPC::Shareable object.
343 Parameters:
345 $attribute
347 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 Attributes are the "OPTIONS" that were used to create the object.
353 Returns: A hash reference of all attributes if $attributes isn't sent
355 in, the value of the specific attribute if it is.
356 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 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
368 IPC::Shareable provides methods to implement application-level advisory
369 locking of the shared data structures. These methods are called
370 "lock()" and "unlock()". To use them you must first get the object
371 underlying the tied variable, either by saving the return value of the
372 original call to "tie()" or by using the built-in "tied()" function.
373 To lock and subsequently unlock a variable, do this:
375 my $knot = tie my %hash, 'IPC::Shareable', { %options };
377 $knot->lock;
379 $hash{a} = 'foo';
380 $knot->unlock;
381 or equivalently, if you've decided to throw away the return of "tie()":
383 tie my %hash, 'IPC::Shareable', { %options };
385 tied(%hash)->lock;
387 $hash{a} = 'foo';
388 tied(%hash)->unlock;
389 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 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 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 If no argument is provided to "lock", it defaults to "LOCK_EX".
406 There are some pitfalls regarding locking and signals about which you
408 should make yourself aware; these are discussed in "NOTES".
409 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 Using the advisory locks can speed up processes that are doing several
415 writes/ reads at the same time.
416
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 IPC::Shareable therefore provides several options to control the timing
424 of removal of shared memory segments.
425 destroy Option
427 As described in "OPTIONS", specifying the destroy option when
428 "tie()"ing a variable coerces IPC::Shareable to remove the underlying
429 shared memory segment when the process calling "tie()" exits
430 gracefully.
431 NOTE: The destruction is handled in an "END" block. Only those memory
433 segments that are tied to the current process will be removed.
434 NOTE: If the segment was created with its "protected" attribute set, it
436 will not be removed in the "END" block, even if "destroy" is set.
437 remove
439 tied($var)->remove;
440 # or
442 $knot->remove;
444 Calling "remove()" on the object underlying a "tie()"d variable removes
446 the associated shared memory segments. The segment is removed
447 irrespective of whether it has the destroy option set or not and
448 irrespective of whether the calling process created the segment.
449 clean_up
451 IPC::Shareable->clean_up;
452 # or
454 tied($var)->clean_up;
456 # or
458 $knot->clean_up;
460 This is a class method that provokes IPC::Shareable to remove all
462 shared memory segments created by the process. Segments not created by
463 the calling process are not removed.
464 This method will not clean up segments created with the "protected"
466 option.
467 clean_up_all
469 IPC::Shareable->clean_up_all;
470 # or
472 tied($var)->clean_up_all;
474 # or
476 $knot->clean_up_all
478 This is a class method that provokes IPC::Shareable to remove all
480 shared memory segments encountered by the process. Segments are
481 removed even if they were not created by the calling process.
482 This method will not clean up segments created with the "protected"
484 option.
485 clean_up_protected($protect_key)
487 If a segment is created with the "protected" option, it, nor its
488 children will be removed during calls of "clean_up()" or
489 "clean_up_all()".
490 When setting "protected", you specified a lock key integer. When
492 calling this method, you must send that integer in as a parameter so we
493 know which segments to clean up.
494 my $protect_key = 93432;
496 IPC::Shareable->clean_up_protected($protect_key);
498 # or
500 tied($var)->clean_up_protected($protect_key;
502 # or
504 $knot->clean_up_protected($protect_key)
506 Parameters:
508 $protect_key
510 Mandatory, Integer: The integer protect key you assigned wit the
512 "protected" option
513
515 Calls to "tie()" that try to implement IPC::Shareable will return an
516 instance of "IPC::Shareable" on success, and "undef" otherwise.
517
519 Benjamin Sugars <bsugars@canoe.ca>
520
522 Steve Bertrand <steveb@cpan.org>
523
525 Footnotes from the above sections
526 1. If the process has been smoked by an untrapped signal, the binding
527 will remain in shared memory. If you're cautious, you might try:
528 $SIG{INT} = \&catch_int;
530 sub catch_int {
531 die;
532 }
533 ...
534 tie $variable, IPC::Shareable, { key => 'GLUE', create => 1, 'destroy' => 1 };
535 which will at least clean up after your user hits CTRL-C because
537 IPC::Shareable's END method will be called. Or, maybe you'd like
538 to leave the binding in shared memory, so subsequent process can
539 recover the data...
540 General Notes
542 o When using "lock()" to lock a variable, be careful to guard against
543 signals. Under normal circumstances, "IPC::Shareable"'s "END"
544 method unlocks any locked variables when the process exits.
545 However, if an untrapped signal is received while a process holds
546 an exclusive lock, "END" will not be called and the lock may be
547 maintained even though the process has exited. If this scares you,
548 you might be better off implementing your own locking methods.
549 One advantage of using "flock" on some known file instead of the
551 locking implemented with semaphores in "IPC::Shareable" is that
552 when a process dies, it automatically releases any locks. This
553 only happens with "IPC::Shareable" if the process dies gracefully.
554 The alternative is to attempt to account for every possible
556 calamitous ending for your process (robust signal handling in Perl
557 is a source of much debate, though it usually works just fine) or
558 to become familiar with your system's tools for removing shared
559 memory and semaphores. This concern should be balanced against the
560 significant performance improvements you can gain for larger data
561 structures by using the locking mechanism implemented in
562 IPC::Shareable.
563 o There is a program called "ipcs"(1/8) (and "ipcrm"(1/8)) that is
565 available on at least Solaris and Linux that might be useful for
566 cleaning moribund shared memory segments or semaphore sets produced
567 by bugs in either IPC::Shareable or applications using it.
568 Examples:
570 # List all semaphores and memory segments in use on the system
572 ipcs -a
574 # List all memory segments and semaphores along with each one's associated process ID
576 ipcs -ap
578 # List just the shared memory segments
580 ipcs -m
582 # List the details of an individual memory segment
584 ipcs -i 12345678
586 # Remove *all* semaphores and memory segments
588 ipcrm -a
590 o This version of IPC::Shareable does not understand the format of
592 shared memory segments created by versions prior to 0.60. If you
593 try to tie to such segments, you will get an error. The only work
594 around is to clear the shared memory segments and start with a
595 fresh set.
596 o Iterating over a hash causes a special optimization if you have not
598 obtained a lock (it is better to obtain a read (or write) lock
599 before iterating over a hash tied to IPC::Shareable, but we attempt
600 this optimization if you do not).
601 For tied hashes, the "fetch"/"thaw" operation is performed when the
603 first key is accessed. Subsequent key and and value accesses are
604 done without accessing shared memory. Doing an assignment to the
605 hash or fetching another value between key accesses causes the hash
606 to be replaced from shared memory. The state of the iterator in
607 this case is not defined by the Perl documentation. Caveat Emptor.
608
610 Thanks to all those with comments or bug fixes, especially
611 Maurice Aubrey <maurice@hevanet.com>
613 Stephane Bortzmeyer <bortzmeyer@pasteur.fr>
614 Doug MacEachern <dougm@telebusiness.co.nz>
615 Robert Emmery <roberte@netscape.com>
616 Mohammed J. Kabir <kabir@intevo.com>
617 Terry Ewing <terry@intevo.com>
618 Tim Fries <timf@dicecorp.com>
619 Joe Thomas <jthomas@women.com>
620 Paul Makepeace <Paul.Makepeace@realprogrammers.com>
621 Raphael Manfredi <Raphael_Manfredi@pobox.com>
622 Lee Lindley <Lee.Lindley@bigfoot.com>
623 Dave Rolsky <autarch@urth.org>
624 Steve Bertrand <steveb@cpan.org>
625
627 perltie, Storable, "shmget", "ipcs", "ipcrm" and other SysV IPC manual
628 pages.
629perl v5.36.0 2022-07-22 IPC::Shareable(3)