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 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 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 the
150 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 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 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 tie()ing
428 a variable coerces IPC::Shareable to remove the underlying shared
429 memory segment when the process calling tie() exits gracefully.
430 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 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 remove
438 tied($var)->remove;
439 # or
441 $knot->remove;
443 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 clean_up
450 IPC::Shareable->clean_up;
451 # or
453 tied($var)->clean_up;
455 # or
457 $knot->clean_up;
459 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 This method will not clean up segments created with the "protected"
465 option.
466 clean_up_all
468 IPC::Shareable->clean_up_all;
469 # or
471 tied($var)->clean_up_all;
473 # or
475 $knot->clean_up_all
477 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 This method will not clean up segments created with the "protected"
483 option.
484 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 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 my $protect_key = 93432;
494 IPC::Shareable->clean_up_protected($protect_key);
496 # or
498 tied($var)->clean_up_protected($protect_key;
500 # or
502 $knot->clean_up_protected($protect_key)
504 Parameters:
506 $protect_key
508 Mandatory, Integer: The integer protect key you assigned wit the
510 "protected" option
511
513 Calls to tie() that try to implement IPC::Shareable will return an
514 instance of "IPC::Shareable" on success, and "undef" otherwise.
515
517 Benjamin Sugars <bsugars@canoe.ca>
518
520 Steve Bertrand <steveb@cpan.org>
521
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 $SIG{INT} = \&catch_int;
528 sub catch_int {
529 die;
530 }
531 ...
532 tie $variable, IPC::Shareable, { key => 'GLUE', create => 1, 'destroy' => 1 };
533 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 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 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 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 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 Examples:
568 # List all semaphores and memory segments in use on the system
570 ipcs -a
572 # List all memory segments and semaphores along with each one's associated process ID
574 ipcs -ap
576 # List just the shared memory segments
578 ipcs -m
580 # List the details of an individual memory segment
582 ipcs -i 12345678
584 # Remove *all* semaphores and memory segments
586 ipcrm -a
588 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 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 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
608 Thanks to all those with comments or bug fixes, especially
609 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
625 perltie, Storable, "shmget", "ipcs", "ipcrm" and other SysV IPC manual
626 pages.
627perl v5.38.0 2023-07-20 IPC::Shareable(3)