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

NAME

6       IPC::ShareLite - Lightweight interface to shared memory
7

VERSION

9       This document describes IPC::ShareLite version 0.17
10

SYNOPSIS

12           use IPC::ShareLite;
13
14           my $share = IPC::ShareLite->new(
15               -key     => 1971,
16               -create  => 'yes',
17               -destroy => 'no'
18           ) or die $!;
19
20           $share->store( "This is stored in shared memory" );
21           my $str = $share->fetch;
22

DESCRIPTION

24       IPC::ShareLite provides a simple interface to shared memory, allowing
25       data to be efficiently communicated between processes. Your operating
26       system must support SysV IPC (shared memory and semaphores) in order to
27       use this module.
28
29       IPC::ShareLite provides an abstraction of the shared memory and
30       semaphore facilities of SysV IPC, allowing the storage of arbitrarily
31       large data; the module automatically acquires and removes shared memory
32       segments as needed. Storage and retrieval of data is atomic, and
33       locking functions are provided for higher-level synchronization.
34
35       In many respects, this module is similar to IPC::Shareable. However,
36       IPC::ShareLite does not provide a tied interface, does not
37       (automatically) allow the storage of variables, and is written in C for
38       additional speed.
39
40       Construct an IPC::ShareLite object by calling its constructor:
41
42           my $share = IPC::ShareLite->new(
43               -key     => 1971,
44               -create  => 'yes',
45               -destroy => 'no'
46           ) or die $!;
47
48       Once an instance has been created, data can be written to shared memory
49       by calling the store() method:
50
51               $share->store("This is going in shared memory");
52
53       Retrieve the data by calling the fetch() method:
54
55               my $str = $share->fetch();
56
57       The store() and fetch() methods are atomic; any processes attempting to
58       read or write to the memory are blocked until these calls finish.
59       However, in certain situations, you'll want to perform multiple
60       operations atomically.  Advisory locking methods are available for this
61       purpose.
62
63       An exclusive lock is obtained by calling the lock() method:
64
65               $share->lock();
66
67       Happily, the lock() method also accepts all of the flags recognized by
68       the flock() system call.  So, for example, you can obtain a shared lock
69       like this:
70
71               $share->lock( LOCK_SH );
72
73       Or, you can make either type of lock non-blocking:
74
75               $share->lock( LOCK_EX|LOCK_NB );
76
77       Release the lock by calling the unlock() method:
78
79               $share->unlock;
80

METHODS

82   "new($key, $create, $destroy, $exclusive, $mode, $flags, $size)"
83       This is the constructor for IPC::ShareLite.  It accepts both the
84       positional and named parameter calling styles.
85
86       $key is an integer value used to associate data between processes.  All
87       processes wishing to communicate should use the same $key value.  $key
88       may also be specified as a four character string, in which case it will
89       be converted to an integer value automatically.  If $key is undefined,
90       the shared memory will not be accessible from other processes.
91
92       $create specifies whether the shared memory segment should be created
93       if it does not already exist.  Acceptable values are 1, 'yes', 0, or
94       'no'.
95
96       $destroy indicates whether the shared memory segments and semaphores
97       should be removed from the system once the object is destroyed.
98       Acceptable values are 1, 'yes', 0, or 'no'.
99
100       If $exclusive is true, instantiation will fail if the shared memory
101       segment already exists. Acceptable values are 1, 'yes', 0, or 'no'.
102
103       $mode specifies the permissions for the shared memory and semaphores.
104       The default value is 0666.
105
106       $flags specifies the exact shared memory and semaphore flags to use.
107       The constants IPC_CREAT, IPC_EXCL, and IPC_PRIVATE are available for
108       import.
109
110       $size specifies the shared memory segment size, in bytes. The default
111       size is 65,536 bytes, which is fairly portable. Linux, as an example,
112       supports segment sizes of 4 megabytes.
113
114       The constructor croaks on error.
115
116   "store( $scalar )"
117       This method stores $scalar into shared memory.  $scalar may be
118       arbitrarily long.  Shared memory segments are acquired and released
119       automatically as the data length changes.  The only limits on the
120       amount of data are the system-wide limits on shared memory pages
121       (SHMALL) and segments (SHMMNI) as compiled into the kernel.
122
123       The method raises an exception on error.
124
125       Note that unlike IPC::Shareable, this module does not automatically
126       allow references to be stored. Serializing all data is expensive, and
127       is not always necessary. If you need to store a reference, you should
128       employ the Storable module yourself. For example:
129
130           use Storable qw( freeze thaw );
131           ...
132               $hash = { red => 1, white => 1, blue => 1 };
133           $share->store( freeze( $hash ) );
134           ...
135           $hash = thaw( $share->fetch );
136
137   "fetch"
138       This method returns the data that was previously stored in shared
139       memory.  The empty string is returned if no data was previously stored.
140
141       The method raises an exception on error.
142
143   "lock( $type )"
144       Obtains a lock on the shared memory.  $type specifies the type of lock
145       to acquire.  If $type is not specified, an exclusive read/write lock is
146       obtained.  Acceptable values for $type are the same as for the flock()
147       system call.  The method returns true on success, and undef on error.
148       For non-blocking calls (see below), the method returns 0 if it would
149       have blocked.
150
151       Obtain an exclusive lock like this:
152
153               $share->lock( LOCK_EX ); # same as default
154
155       Only one process can hold an exclusive lock on the shared memory at a
156       given time.
157
158       Obtain a shared lock this this:
159
160               $share->lock( LOCK_SH );
161
162       Multiple processes can hold a shared lock at a given time.  If a
163       process attempts to obtain an exclusive lock while one or more
164       processes hold shared locks, it will be blocked until they have all
165       finished.
166
167       Either of the locks may be specified as non-blocking:
168
169               $share->lock( LOCK_EX|LOCK_NB );
170               $share->lock( LOCK_SH|LOCK_NB );
171
172       A non-blocking lock request will return 0 if it would have had to wait
173       to obtain the lock.
174
175       Note that these locks are advisory (just like flock), meaning that all
176       cooperating processes must coordinate their accesses to shared memory
177       using these calls in order for locking to work.  See the flock() call
178       for details.
179
180       Locks are inherited through forks, which means that two processes
181       actually can possess an exclusive lock at the same time.  Don't do
182       that.
183
184       The constants LOCK_EX, LOCK_SH, LOCK_NB, and LOCK_UN are available for
185       import:
186
187               use IPC::ShareLite qw( :lock );
188
189       Or, just use the flock constants available in the Fcntl module.
190
191   "unlock"
192       Releases any locks.  This is actually equivalent to:
193
194               $share->lock( LOCK_UN );
195
196       The method returns true on success and undef on error.
197
198   "version"
199       Each share has a version number that incrementents monotonically for
200       each write to the share. When the share is initally created its version
201       number will be 1.
202
203           my $num_writes = $share->version;
204
205   "key"
206       Get a share's key.
207
208           my $key = $share->key;
209
210   "create"
211       Get a share's create flag.
212
213   "exclusive"
214       Get a share's exclusive flag.
215
216   "flags"
217       Get a share's flag.
218
219   "mode"
220       Get a share's mode.
221
222   "size"
223       Get a share's segment size.
224
225   "num_segments"
226       Get the number of segments in a share. The memory usage of a share can
227       be approximated like this:
228
229           my $usage = $share->size * $share->num_segments;
230
231       $usage will be the memory usage rounded up to the next segment
232       boundary.
233
234   "destroy"
235       Get or set the share's destroy flag.
236

PERFORMANCE

238       For a rough idea of the performance you can expect, here are some
239       benchmarks.  The tests were performed using the Benchmark module on a
240       Cyrix PR166+ running RedHat Linux 5.2 with the 2.0.36 kernel, perl
241       5.005_02 using perl's malloc, and the default shared memory segment
242       size.  Each test was run 5000 times.
243
244               DATA SIZE (bytes)       TIME (seconds)  Op/Sec
245
246        store  16384                   2               2500
247        fetch  16384                   2               2500
248
249        store  32768                   3               1666
250        fetch  32768                   3               1666
251
252        store  65536                   6               833
253        fetch  65536                   5               1000
254
255        store  131072                  12              416
256        fetch  131072                  12              416
257
258        store  262144                  28              178
259        fetch  262144                  27              185
260
261        store  524288                  63              79
262        fetch  524288                  61              81
263
264       Most of the time appears to be due to memory copying.  Suggestions for
265       speed improvements are welcome.
266

PORTABILITY

268       The module should compile on any system with SysV IPC and an ANSI C
269       compiler, and should compile cleanly with the -pedantic and -Wall
270       flags.
271
272       The module has been tested under Solaris, FreeBSD, and Linux.  Testing
273       on other platforms is needed.
274
275       If you encounter a compilation error due to the definition of the semun
276       union, edit the top of sharestuff.c and undefine the semun definition.
277       And then please tell me about it.
278
279       I've heard rumors that a SysV IPC interface has been constructed for
280       Win32 systems.  Support for it may be added to this module.
281
282       IPC::ShareLite does not understand the shared memory data format used
283       by IPC::Shareable.
284

AUTHOR

286       Copyright 1998-2002, Maurice Aubrey <maurice@hevanet.com>.  All rights
287       reserved.
288
289       This release by Andy Armstrong <andy@hexten.net>.
290
291       This module is free software; you may redistribute it and/or modify it
292       under the same terms as Perl itself.
293

CREDITS

295       Special thanks to Benjamin Sugars for developing the IPC::Shareable
296       module.
297
298       See the Changes file for other contributors.
299

SEE ALSO

301       IPC::Shareable, ipc(2), shmget(2), semget(2), perl.
302
303
304
305perl v5.12.1                      2009-03-11                 IPC::ShareLite(3)
Impressum