1IPC::ShareLite(3) User Contributed Perl Documentation IPC::ShareLite(3)
2
6 IPC::ShareLite - Lightweight interface to shared memory
7
9 This document describes IPC::ShareLite version 0.17
10
12 use IPC::ShareLite;
13 my $share = IPC::ShareLite->new(
15 -key => 1971,
16 -create => 'yes',
17 -destroy => 'no'
18 ) or die $!;
19 $share->store( "This is stored in shared memory" );
21 my $str = $share->fetch;
22
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 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 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 Construct an IPC::ShareLite object by calling its constructor:
41 my $share = IPC::ShareLite->new(
43 -key => 1971,
44 -create => 'yes',
45 -destroy => 'no'
46 ) or die $!;
47 Once an instance has been created, data can be written to shared memory
49 by calling the store() method:
50 $share->store("This is going in shared memory");
52 Retrieve the data by calling the fetch() method:
54 my $str = $share->fetch();
56 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 An exclusive lock is obtained by calling the lock() method:
64 $share->lock();
66 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 $share->lock( LOCK_SH );
72 Or, you can make either type of lock non-blocking:
74 $share->lock( LOCK_EX|LOCK_NB );
76 Release the lock by calling the unlock() method:
78 $share->unlock;
80
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 $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 $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 $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 If $exclusive is true, instantiation will fail if the shared memory
101 segment already exists. Acceptable values are 1, 'yes', 0, or 'no'.
102 $mode specifies the permissions for the shared memory and semaphores.
104 The default value is 0666.
105 $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 $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 The constructor croaks on error.
115 "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 The method raises an exception on error.
124 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 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 "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 The method raises an exception on error.
142 "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 Obtain an exclusive lock like this:
152 $share->lock( LOCK_EX ); # same as default
154 Only one process can hold an exclusive lock on the shared memory at a
156 given time.
157 Obtain a shared lock this this:
159 $share->lock( LOCK_SH );
161 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 Either of the locks may be specified as non-blocking:
168 $share->lock( LOCK_EX|LOCK_NB );
170 $share->lock( LOCK_SH|LOCK_NB );
171 A non-blocking lock request will return 0 if it would have had to wait
173 to obtain the lock.
174 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 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 The constants LOCK_EX, LOCK_SH, LOCK_NB, and LOCK_UN are available for
185 import:
186 use IPC::ShareLite qw( :lock );
188 Or, just use the flock constants available in the Fcntl module.
190 "unlock"
192 Releases any locks. This is actually equivalent to:
193 $share->lock( LOCK_UN );
195 The method returns true on success and undef on error.
197 "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 my $num_writes = $share->version;
204 "key"
206 Get a share's key.
207 my $key = $share->key;
209 "create"
211 Get a share's create flag.
212 "exclusive"
214 Get a share's exclusive flag.
215 "flags"
217 Get a share's flag.
218 "mode"
220 Get a share's mode.
221 "size"
223 Get a share's segment size.
224 "num_segments"
226 Get the number of segments in a share. The memory usage of a share can
227 be approximated like this:
228 my $usage = $share->size * $share->num_segments;
230 $usage will be the memory usage rounded up to the next segment
232 boundary.
233 "destroy"
235 Get or set the share's destroy flag.
236
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 DATA SIZE (bytes) TIME (seconds) Op/Sec
245 store 16384 2 2500
247 fetch 16384 2 2500
248 store 32768 3 1666
250 fetch 32768 3 1666
251 store 65536 6 833
253 fetch 65536 5 1000
254 store 131072 12 416
256 fetch 131072 12 416
257 store 262144 28 178
259 fetch 262144 27 185
260 store 524288 63 79
262 fetch 524288 61 81
263 Most of the time appears to be due to memory copying. Suggestions for
265 speed improvements are welcome.
266
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 The module has been tested under Solaris, FreeBSD, and Linux. Testing
273 on other platforms is needed.
274 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 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 IPC::ShareLite does not understand the shared memory data format used
283 by IPC::Shareable.
284
286 Copyright 1998-2002, Maurice Aubrey <maurice@hevanet.com>. All rights
287 reserved.
288 This release by Andy Armstrong <andy@hexten.net>.
290 This module is free software; you may redistribute it and/or modify it
292 under the same terms as Perl itself.
293
295 Special thanks to Benjamin Sugars for developing the IPC::Shareable
296 module.
297 See the Changes file for other contributors.
299
301 IPC::Shareable, ipc(2), shmget(2), semget(2), perl.
302perl v5.28.1 2009-03-11 IPC::ShareLite(3)