IPC::ShareLite(3pm)

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

NAME

6       IPC::ShareLite - Light-weight interface to shared memory
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

74       new($key, $create, $destroy, $exclusive, $mode, $flags, $size)
75           This is the constructor for IPC::ShareLite.  It accepts both the
76           positional and named parameter calling styles.
77
78           $key is an integer value used to associate data between processes.
79           All processes wishing to communicate should use the same $key
80           value.  $key may also be specified as a four character string, in
81           which case it will be converted to an integer value automatically.
82           If $key is undefined, the shared memory will not be accessible from
83           other processes.
84
85           $create specifies whether the shared memory segment should be cre‐
86           ated if it does not already exist.  Acceptable values are 1, 'yes',
87           0, or 'no'.
88
89           $destroy indicates whether the shared memory segments and sema‐
90           phores should be removed from the system once the object is
91           destroyed.  Acceptable values are 1, 'yes', 0, or 'no'.
92
93           If $exclusive is true, instantiation will fail if the shared memory
94           segment already exists.  Acceptable values are 1, 'yes', 0, or
95           'no'.
96
97           $mode specifies the permissions for the shared memory and sema‐
98           phores.  The default value is 0666.
99
100           $flags specifies the exact shared memory and semaphore flags to
101           use.  The constants IPC_CREAT, IPC_EXCL, and IPC_PRIVATE are avail‐
102           able for import.
103
104           $size specifies the shared memory segment size, in bytes.  The
105           default size is 65,536 bytes, which is fairly portable.  Linux, as
106           an example, supports segment sizes of 4 megabytes.
107
108           The constructor returns the undefined value on error.
109
110       store( $scalar )
111           This method stores $scalar into shared memory.  $scalar may be
112           arbitrarily long.  Shared memory segments are acquired and released
113           automatically as the data length changes.  The only limits on the
114           amount of data are the system-wide limits on shared memory pages
115           (SHMALL) and segments (SHMMNI) as compiled into the kernel.
116
117           Note that unlike IPC::Shareable, this module does not automatically
118           allow variables to be stored.  Serializing all data is expensive,
119           and is not always necessary.  If you need to store a variable, you
120           should employ the Storable module yourself.  For example:
121
122                   use Storable qw( freeze thaw );
123                   ...
124                   $hash = { red => 1, white => 1, blue => 1 };
125                   $share->store( freeze( $hash ) );
126                   ...
127                   $hash = thaw( $share->fetch );
128
129           The method raises an exception on error.
130
131       fetch()
132           This method returns the data that was previously stored in shared
133           memory.  The empty string is returned if no data was previously
134           stored.
135
136           The method raises an exception on error.
137
138       lock( $type )
139           Obtains a lock on the shared memory.  $type specifies the type of
140           lock to acquire.  If $type is not specified, an exclusive
141           read/write lock is obtained.  Acceptable values for $type are the
142           same as for the flock() system call.  The method returns true on
143           success, and undef on error.  For non-blocking calls (see below),
144           the method returns 0 if it would have blocked.
145
146           Obtain an exclusive lock like this:
147
148                   $share->lock( LOCK_EX ); # same as default
149
150           Only one process can hold an exclusive lock on the shared memory at
151           a given time.
152
153           Obtain a shared lock this this:
154
155                   $share->lock( LOCK_SH );
156
157           Multiple processes can hold a shared lock at a given time.  If a
158           process attempts to obtain an exclusive lock while one or more pro‐
159           cesses hold shared locks, it will be blocked until they have all
160           finished.
161
162           Either of the locks may be specified as non-blocking:
163
164                   $share->lock( LOCK_EX⎪LOCK_NB );
165                   $share->lock( LOCK_SH⎪LOCK_NB );
166
167           A non-blocking lock request will return 0 if it would have had to
168           wait to obtain the lock.
169
170           Note that these locks are advisory (just like flock), meaning that
171           all cooperating processes must coordinate their accesses to shared
172           memory using these calls in order for locking to work.  See the
173           flock() call for details.
174
175           Locks are inherited through forks, which means that two processes
176           actually can possess an exclusive lock at the same time.  Don't do
177           that.
178
179           The constants LOCK_EX, LOCK_SH, LOCK_NB, and LOCK_UN are available
180           for import:
181
182                   use IPC::ShareLite qw( :lock );
183
184           Or, just use the flock constants available in the Fcntl module.
185
186       unlock()
187           Releases any locks.  This is actually equivalent to:
188
189                   $share->lock( LOCK_UN );
190
191           The method returns true on success and undef on error.
192

PERFORMANCE

194       For a rough idea of the performance you can expect, here are some
195       benchmarks.  The tests were performed using the Benchmark module on a
196       Cyrix PR166+ running RedHat Linux 5.2 with the 2.0.36 kernel, perl
197       5.005_02 using perl's malloc, and the default shared memory segment
198       size.  Each test was run 5000 times.
199
200               DATA SIZE (bytes)       TIME (seconds)  Op/Sec
201
202        store  16384                   2               2500
203        fetch  16384                   2               2500
204
205        store  32768                   3               1666
206        fetch  32768                   3               1666
207
208        store  65536                   6               833
209        fetch  65536                   5               1000
210
211        store  131072                  12              416
212        fetch  131072                  12              416
213
214        store  262144                  28              178
215        fetch  262144                  27              185
216
217        store  524288                  63              79
218        fetch  524288                  61              81
219
220       Most of the time appears to be due to memory copying.  Suggestions for
221       speed improvements are welcome.
222

PORTABILITY

224       The module should compile on any system with SysV IPC and an ANSI C
225       compiler, and should compile cleanly with the -pedantic and -Wall
226       flags.
227
228       The module has been tested under Solaris, FreeBSD, and Linux.  Testing
229       on other platforms is needed.
230
231       If you encounter a compilation error due to the definition of the semun
232       union, edit the top of sharelite.c and undefine the semun definition.
233       And then please tell me about it.
234
235       I've heard rumors that a SysV IPC interface has been constructed for
236       Win32 systems.  Support for it may be added to this module.
237
238       IPC::ShareLite does not understand the shared memory data format used
239       by IPC::Shareable.
240

AUTHOR

242       Copyright 1998-2002, Maurice Aubrey <maurice@hevanet.com>.  All rights
243       reserved.
244
245       This module is free software; you may redistribute it and/or modify it
246       under the same terms as Perl itself.
247

CREDITS

249       Special thanks to Benjamin Sugars for developing the IPC::Shareable
250       module.
251
252       See the Changes file for other contributors.
253