IPC::ShareLite man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

ShareLite(3)	      User Contributed Perl Documentation	  ShareLite(3)

NAME
       IPC::ShareLite - Light-weight interface to shared memory

SYNOPSIS
	 use IPC::ShareLite;

	 $share = new IPC::ShareLite( -key     => 1971,
				      -create  => 'yes',
				      -destroy => 'no' ) or die $!;

	 $share->store("This is stored in shared memory");
	 $str = $share->fetch;

DESCRIPTION
       IPC::ShareLite provides a simple interface to shared memory, allowing
       data to be efficiently communicated between processes.  Your operating
       system must support SysV IPC (shared memory and semaphores) in order to
       use this module.

       IPC::ShareLite provides an abstraction of the shared memory and sema-
       phore facilities of SysV IPC, allowing the storage of arbitrarily large
       data; the module automatically acquires and removes shared memory seg-
       ments as needed.	 Storage and retrieval of data is atomic, and locking
       functions are provided for higher-level synchronization.

       In many respects, this module is similar to IPC::Shareable.  However,
       IPC::ShareLite does not provide a tied interface, does not (automati-
       cally) allow the storage of variables, and is written in C for addi-
       tional speed.

       Construct an IPC::ShareLite object by calling its constructor:

	       $share = new IPC::ShareLite( -key     => 1971,
					    -create  => 'yes',
					    -destroy => 'no' ) or die $!;

       Once an instance has been created, data can be written to shared memory
       by calling the store() method:

	       $share->store("This is going in shared memory");

       Retrieve the data by calling the fetch() method:

	       $str = $share->fetch();

       The store() and fetch() methods are atomic; any processes attempting to
       read or write to the memory are blocked until these calls finish.  How-
       ever, in certain situations, you'll want to perform multiple operations
       atomically.  Advisory locking methods are available for this purpose.

       An exclusive lock is obtained by calling the lock() method:

	       $share->lock();

       Happily, the lock() method also accepts all of the flags recognized by
       the flock() system call.	 So, for example, you can obtain a shared lock
       like this:

	       $share->lock( LOCK_SH );

       Or, you can make either type of lock non-blocking:

	       $share->lock( LOCK_EX|LOCK_NB );

       Release the lock by calling the unlock() method:

	       $share->unlock;

METHODS
       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.

	   $key is an integer value used to associate data between processes.
	   All processes wishing to communicate should use the same $key
	   value.  $key may also be specified as a four character string, in
	   which case it will be converted to an integer value automatically.
	   If $key is undefined, the shared memory will not be accessible from
	   other processes.

	   $create specifies whether the shared memory segment should be cre-
	   ated if it does not already exist.  Acceptable values are 1, 'yes',
	   0, or 'no'.

	   $destroy indicates whether the shared memory segments and sema-
	   phores should be removed from the system once the object is
	   destroyed.  Acceptable values are 1, 'yes', 0, or 'no'.

	   If $exclusive is true, instantiation will fail if the shared memory
	   segment already exists.  Acceptable values are 1, 'yes', 0, or
	   'no'.

	   $mode specifies the permissions for the shared memory and sema-
	   phores.  The default value is 0666.

	   $flags specifies the exact shared memory and semaphore flags to
	   use.	 The constants IPC_CREAT, IPC_EXCL, and IPC_PRIVATE are avail-
	   able for import.

	   $size 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.

	   The constructor returns the undefined value on error.

       store( $scalar )
	   This method stores $scalar into shared memory.  $scalar 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
	   (SHMALL) and segments (SHMMNI) as compiled into the kernel.

	   Note that unlike IPC::Shareable, this module does not automatically
	   allow variables to be stored.  Serializing all data is expensive,
	   and is not always necessary.	 If you need to store a variable, you
	   should employ the Storable module yourself.	For example:

		   use Storable qw( freeze thaw );
		   ...
		   $hash = { red => 1, white => 1, blue => 1 };
		   $share->store( freeze( $hash ) );
		   ...
		   $hash = thaw( $share->fetch );

	   The method raises an exception on error.

       fetch()
	   This method returns the data that was previously stored in shared
	   memory.  The empty string is returned if no data was previously
	   stored.

	   The method raises an exception on error.

       lock( $type )
	   Obtains a lock on the shared memory.	 $type specifies the type of
	   lock to acquire.  If $type is not specified, an exclusive
	   read/write lock is obtained.	 Acceptable values for $type are the
	   same as for the flock() 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.

	   Obtain an exclusive lock like this:

		   $share->lock( LOCK_EX ); # same as default

	   Only one process can hold an exclusive lock on the shared memory at
	   a given time.

	   Obtain a shared lock this this:

		   $share->lock( LOCK_SH );

	   Multiple processes can hold a shared lock at a given time.  If a
	   process attempts to obtain an exclusive lock while one or more pro-
	   cesses hold shared locks, it will be blocked until they have all
	   finished.

	   Either of the locks may be specified as non-blocking:

		   $share->lock( LOCK_EX|LOCK_NB );
		   $share->lock( LOCK_SH|LOCK_NB );

	   A non-blocking lock request will return 0 if it would have had to
	   wait to obtain the lock.

	   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
	   flock() call for details.

	   Locks are inherited through forks, which means that two processes
	   actually can possess an exclusive lock at the same time.  Don't do
	   that.

	   The constants LOCK_EX, LOCK_SH, LOCK_NB, and LOCK_UN are available
	   for import:

		   use IPC::ShareLite qw( :lock );

	   Or, just use the flock constants available in the Fcntl module.

       unlock()
	   Releases any locks.	This is actually equivalent to:

		   $share->lock( LOCK_UN );

	   The method returns true on success and undef on error.

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 PR166+ 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.

	       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

       Most of the time appears to be due to memory copying.  Suggestions for
       speed improvements are welcome.

PORTABILITY
       The module should compile on any system with SysV IPC and an ANSI C
       compiler, and should compile cleanly with the -pedantic and -Wall
       flags.

       The module has been tested under Solaris, FreeBSD, and Linux.  Testing
       on other platforms is needed.

       If you encounter a compilation error due to the definition of the semun
       union, edit the top of sharelite.c and undefine the semun definition.
       And then please tell me about it.

       I've heard rumors that a SysV IPC interface has been constructed for
       Win32 systems.  Support for it may be added to this module.

       IPC::ShareLite does not understand the shared memory data format used
       by IPC::Shareable.

AUTHOR
       Copyright 1998-2002, Maurice Aubrey <maurice@hevanet.com>.  All rights
       reserved.

       This module is free software; you may redistribute it and/or modify it
       under the same terms as Perl itself.

CREDITS
       Special thanks to Benjamin Sugars for developing the IPC::Shareable
       module.

       See the Changes file for other contributors.

SEE ALSO
       IPC::Shareable, ipc(2), shmget(2), semget(2), perl.

perl v5.8.8			  2002-12-04			  ShareLite(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net