.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IPC::ShareLite 3pm"
.TH IPC::ShareLite 3pm "2009-03-11" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IPC::ShareLite \- Lightweight interface to shared memory
.SH "VERSION"
.IX Header "VERSION"
This document describes IPC::ShareLite version 0.17
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use IPC::ShareLite;
\&
\&    my $share = IPC::ShareLite\->new(
\&        \-key     => 1971,
\&        \-create  => \*(Aqyes\*(Aq,
\&        \-destroy => \*(Aqno\*(Aq
\&    ) or die $!;
\&
\&    $share\->store( "This is stored in shared memory" );
\&    my $str = $share\->fetch;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
IPC::ShareLite provides a simple interface to shared memory, allowing
data to be efficiently communicated between processes. Your operating
system must support SysV \s-1IPC \s0(shared memory and semaphores) in order to
use this module.
.PP
IPC::ShareLite provides an abstraction of the shared memory and
semaphore facilities of SysV \s-1IPC,\s0 allowing the storage of arbitrarily
large data; the module automatically acquires and removes shared memory
segments as needed. Storage and retrieval of data is atomic, and locking
functions are provided for higher-level synchronization.
.PP
In many respects, this module is similar to IPC::Shareable. However,
IPC::ShareLite does not provide a tied interface, does not 
(automatically) allow the storage of variables, and is written in C
for additional speed.
.PP
Construct an IPC::ShareLite object by calling its constructor:
.PP
.Vb 5
\&    my $share = IPC::ShareLite\->new(
\&        \-key     => 1971,
\&        \-create  => \*(Aqyes\*(Aq,
\&        \-destroy => \*(Aqno\*(Aq
\&    ) or die $!;
.Ve
.PP
Once an instance has been created, data can be written to shared memory
by calling the \fIstore()\fR method:
.PP
.Vb 1
\&        $share\->store("This is going in shared memory");
.Ve
.PP
Retrieve the data by calling the \fIfetch()\fR method:
.PP
.Vb 1
\&        my $str = $share\->fetch();
.Ve
.PP
The \fIstore()\fR and \fIfetch()\fR methods are atomic; any processes attempting
to read or write to the memory are blocked until these calls finish.
However, in certain situations, you'll want to perform multiple
operations atomically.  Advisory locking methods are available for 
this purpose.
.PP
An exclusive lock is obtained by calling the \fIlock()\fR method:
.PP
.Vb 1
\&        $share\->lock();
.Ve
.PP
Happily, the \fIlock()\fR method also accepts all of the flags recognized
by the \fIflock()\fR system call.  So, for example, you can obtain a
shared lock like this:
.PP
.Vb 1
\&        $share\->lock( LOCK_SH );
.Ve
.PP
Or, you can make either type of lock non-blocking:
.PP
.Vb 1
\&        $share\->lock( LOCK_EX|LOCK_NB );
.Ve
.PP
Release the lock by calling the \fIunlock()\fR method:
.PP
.Vb 1
\&        $share\->unlock;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """new($key, $create, $destroy, $exclusive, $mode, $flags, $size)"""
.el .SS "\f(CWnew($key, $create, $destroy, $exclusive, $mode, $flags, $size)\fP"
.IX Subsection "new($key, $create, $destroy, $exclusive, $mode, $flags, $size)"
This is the constructor for IPC::ShareLite.  It accepts both 
the positional and named parameter calling styles.
.PP
\&\f(CW$key\fR is an integer value used to associate data between processes.
All processes wishing to communicate should use the same \f(CW$key\fR value.
\&\f(CW$key\fR may also be specified as a four character string, in which case
it will be converted to an integer value automatically.  If \f(CW$key\fR
is undefined, the shared memory will not be accessible from other
processes.
.PP
\&\f(CW$create\fR specifies whether the shared memory segment should be
created if it does not already exist.  Acceptable values are
1, 'yes', 0, or 'no'.
.PP
\&\f(CW$destroy\fR indicates whether the shared memory segments and semaphores
should be removed from the system once the object is destroyed.
Acceptable values are 1, 'yes', 0, or 'no'.
.PP
If \f(CW$exclusive\fR is true, instantiation will fail if the shared memory
segment already exists. Acceptable values are 1, 'yes', 0, or 'no'.
.PP
\&\f(CW$mode\fR specifies the permissions for the shared memory and semaphores.
The default value is 0666.
.PP
\&\f(CW$flags\fR specifies the exact shared memory and semaphore flags to
use. The constants \s-1IPC_CREAT, IPC_EXCL,\s0 and \s-1IPC_PRIVATE\s0 are available
for import.
.PP
\&\f(CW$size\fR specifies the shared memory segment size, in bytes. The default
size is 65,536 bytes, which is fairly portable. Linux, as an example,
supports segment sizes of 4 megabytes.
.PP
The constructor croaks on error.
.ie n .SS """store( $scalar )"""
.el .SS "\f(CWstore( $scalar )\fP"
.IX Subsection "store( $scalar )"
This method stores \f(CW$scalar\fR into shared memory.  \f(CW$scalar\fR may be
arbitrarily long.  Shared memory segments are acquired and
released automatically as the data length changes.
The only limits on the amount of data are the system-wide
limits on shared memory pages (\s-1SHMALL\s0) and segments (\s-1SHMMNI\s0)
as compiled into the kernel.
.PP
The method raises an exception on error.
.PP
Note that unlike IPC::Shareable, this module does not automatically
allow references to be stored. Serializing all data is expensive, and is
not always necessary. If you need to store a reference, you should employ
the Storable module yourself. For example:
.PP
.Vb 6
\&    use Storable qw( freeze thaw );
\&    ...
\&        $hash = { red => 1, white => 1, blue => 1 };
\&    $share\->store( freeze( $hash ) );
\&    ...
\&    $hash = thaw( $share\->fetch );
.Ve
.ie n .SS """fetch"""
.el .SS "\f(CWfetch\fP"
.IX Subsection "fetch"
This method returns the data that was previously stored in
shared memory.  The empty string is returned if no data was
previously stored.
.PP
The method raises an exception on error.
.ie n .SS """lock( $type )"""
.el .SS "\f(CWlock( $type )\fP"
.IX Subsection "lock( $type )"
Obtains a lock on the shared memory.  \f(CW$type\fR specifies the type
of lock to acquire.  If \f(CW$type\fR is not specified, an exclusive
read/write lock is obtained.  Acceptable values for \f(CW$type\fR are
the same as for the \fIflock()\fR system call.  The method returns
true on success, and undef on error.  For non-blocking calls
(see below), the method returns 0 if it would have blocked.
.PP
Obtain an exclusive lock like this:
.PP
.Vb 1
\&        $share\->lock( LOCK_EX ); # same as default
.Ve
.PP
Only one process can hold an exclusive lock on the shared memory at
a given time.
.PP
Obtain a shared lock this this:
.PP
.Vb 1
\&        $share\->lock( LOCK_SH );
.Ve
.PP
Multiple processes can hold a shared lock at a given time.  If a process
attempts to obtain an exclusive lock while one or more processes hold
shared locks, it will be blocked until they have all finished.
.PP
Either of the locks may be specified as non-blocking:
.PP
.Vb 2
\&        $share\->lock( LOCK_EX|LOCK_NB );
\&        $share\->lock( LOCK_SH|LOCK_NB );
.Ve
.PP
A non-blocking lock request will return 0 if it would have had to
wait to obtain the lock.
.PP
Note that these locks are advisory (just like flock), meaning that
all cooperating processes must coordinate their accesses to shared memory
using these calls in order for locking to work.  See the \fIflock()\fR call for 
details.
.PP
Locks are inherited through forks, which means that two processes actually
can possess an exclusive lock at the same time.  Don't do that.
.PP
The constants \s-1LOCK_EX, LOCK_SH, LOCK_NB,\s0 and \s-1LOCK_UN\s0 are available
for import:
.PP
.Vb 1
\&        use IPC::ShareLite qw( :lock );
.Ve
.PP
Or, just use the flock constants available in the Fcntl module.
.ie n .SS """unlock"""
.el .SS "\f(CWunlock\fP"
.IX Subsection "unlock"
Releases any locks.  This is actually equivalent to:
.PP
.Vb 1
\&        $share\->lock( LOCK_UN );
.Ve
.PP
The method returns true on success and undef on error.
.ie n .SS """version"""
.el .SS "\f(CWversion\fP"
.IX Subsection "version"
Each share has a version number that incrementents monotonically for
each write to the share. When the share is initally created its version
number will be 1.
.PP
.Vb 1
\&    my $num_writes = $share\->version;
.Ve
.ie n .SS """key"""
.el .SS "\f(CWkey\fP"
.IX Subsection "key"
Get a share's key.
.PP
.Vb 1
\&    my $key = $share\->key;
.Ve
.ie n .SS """create"""
.el .SS "\f(CWcreate\fP"
.IX Subsection "create"
Get a share's create flag.
.ie n .SS """exclusive"""
.el .SS "\f(CWexclusive\fP"
.IX Subsection "exclusive"
Get a share's exclusive flag.
.ie n .SS """flags"""
.el .SS "\f(CWflags\fP"
.IX Subsection "flags"
Get a share's flag.
.ie n .SS """mode"""
.el .SS "\f(CWmode\fP"
.IX Subsection "mode"
Get a share's mode.
.ie n .SS """size"""
.el .SS "\f(CWsize\fP"
.IX Subsection "size"
Get a share's segment size.
.ie n .SS """num_segments"""
.el .SS "\f(CWnum_segments\fP"
.IX Subsection "num_segments"
Get the number of segments in a share. The memory usage of a share can
be approximated like this:
.PP
.Vb 1
\&    my $usage = $share\->size * $share\->num_segments;
.Ve
.PP
\&\f(CW$usage\fR will be the memory usage rounded up to the next segment
boundary.
.ie n .SS """destroy"""
.el .SS "\f(CWdestroy\fP"
.IX Subsection "destroy"
Get or set the share's destroy flag.
.SH "PERFORMANCE"
.IX Header "PERFORMANCE"
For a rough idea of the performance you can expect, here are some
benchmarks.  The tests were performed using the Benchmark module
on a Cyrix \s-1PR166+\s0 running RedHat Linux 5.2 with the 2.0.36 kernel,
perl 5.005_02 using perl's malloc, and the default shared memory
segment size.  Each test was run 5000 times.
.PP
.Vb 1
\&        DATA SIZE (bytes)       TIME (seconds)  Op/Sec
\&
\& store  16384                   2               2500
\& fetch  16384                   2               2500
\&
\& store  32768                   3               1666    
\& fetch  32768                   3               1666    
\&
\& store  65536                   6               833
\& fetch  65536                   5               1000    
\&
\& store  131072                  12              416     
\& fetch  131072                  12              416     
\&
\& store  262144                  28              178     
\& fetch  262144                  27              185     
\&
\& store  524288                  63              79      
\& fetch  524288                  61              81
.Ve
.PP
Most of the time appears to be due to memory copying.  
Suggestions for speed improvements are welcome.
.SH "PORTABILITY"
.IX Header "PORTABILITY"
The module should compile on any system with SysV \s-1IPC\s0 and
an \s-1ANSI C\s0 compiler, and should compile cleanly with the
\&\-pedantic and \-Wall flags.
.PP
The module has been tested under Solaris, FreeBSD, and Linux.
Testing on other platforms is needed.
.PP
If you encounter a compilation error due to the definition
of the semun union, edit the top of sharestuff.c and undefine
the semun definition.  And then please tell me about it.
.PP
I've heard rumors that a SysV \s-1IPC\s0 interface has been 
constructed for Win32 systems.  Support for it may be
added to this module.
.PP
IPC::ShareLite does not understand the shared memory
data format used by IPC::Shareable.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright 1998\-2002, Maurice Aubrey <maurice@hevanet.com>. 
All rights reserved.
.PP
This release by Andy Armstrong <andy@hexten.net>.
.PP
This module is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.
.SH "CREDITS"
.IX Header "CREDITS"
Special thanks to Benjamin Sugars for developing the
IPC::Shareable module.
.PP
See the Changes file for other contributors.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IPC::Shareable, \fIipc\fR\|(2), \fIshmget\fR\|(2), \fIsemget\fR\|(2), perl.