DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

/usr/man/cat.3/IPC::MM.3.Z





NAME

       IPC::MM - Perl interface to Ralf Engelschall's mm library


SYNOPSIS

         use IPC::MM;

         $MMSIZE = 65536;
         $MMFILE = 'mm_file';

         $mm = mm_create($MMSIZE, $MM_FILE);

         $scalar = mm_make_scalar($mm);
         tie $tied_scalar, 'IPC::MM::Scalar', $scalar;
         $tied_scalar = 'hello';

         $btree = mm_make_btree_table($mm);
         tie %tied_hash, 'IPC::MM::BTree', $btree;
         $tied_hash{key} = 'val';

         $hash = mm_make_hash($mm);
         tie %tied_hash, 'IPC::MM::Hash', $hash;
         $tied_hash{key} = 'val';

         $num = mm_maxsize();

         $num = mm_available($mm);

         $errstr = mm_error();

         mm_display_info($mm);

         mm_destroy($mm);


DESCRIPTION

       IPC::MM provides an interface to Ralf Engelschall's mm library, allow-
       ing memory to be shared between multiple processes in a relatively con-
       venient way.

       IPC::MM provides methods to create and destoy shared memory segments
       and to access data structures within those shared memory segments, as
       well as miscellaneous methods. Additionally, it provides a tied inter-
       face for scalars and hashes.


METHODS

       $mm = mm_create($size, $file)
           This method creates a shared memory segment. It corresponds to the
           function in mm of the same name.

           $size is the size of the shared memory segment, in bytes. A size of
           0 means to allocate the maximum allowed size which is platform
           dependent.

           $file is a filesystem path to a file which may be used as a lock
           file for synchronizing access.

       $rc = mm_permission($mm, $mode, $owner, $group)
           This method sets the filesystem mode, owner, and group for the
           shared memory segment mm. It will only do anything when the under-
           lying shared memory segment is based on files. It corresponds to
           the function in mm of the same name.

           $mm is the shared memory segment returned by mm_create.

           $mode, $owner, and $group are passed directly to chown and chmod.

       mm_destroy($mm)
           This method destroys a shared memory segment created by mm_create.

           $mm is the shared memory segment returned by mm_create.

       $scalar = mm_make_scalar($mm)
       mm_free_scalar($scalar)
       $val = mm_scalar_get($scalar)
       $rc = mm_scalar_set($scalar, $val)
           This family of methods provides a data structure for use by scalar
           variables.

           mm_make_scalar allocates the data structure used by the scalar.

           mm_free_scalar frees a data structure created by mm_make_scalar.

           mm_scalar_get returns the contents of the scalar, $scalar.

           mm_scalar_set sets the contents of the scalar, $scalar, to $val.

           $val is simply a Perl scalar value, meaning that it can be a
           string, a number, a reference, et al.

           It is possible for mm_scalar_set to fail if there is not enough
           shared memory.

           It is possible to make the scalar a tied variable, like so:

             tie $tied_scalar, 'IPC::MM::Scalar', $scalar;

       $btree = mm_make_btree_table($mm)
       mm_clear_btree_table($btree)
       mm_free_btree_table($btree)
       $val = mm_btree_table_get($btree, $key)
       $rc = mm_btree_table_insert($btree, $key, $val)
       $oldval = mm_btree_table_delete($btree, $key)
       $rc = mm_btree_table_exists($btree, $key)
       $key = mm_btree_table_first_key($btree)
       $key = mm_btree_table_next_key($btree, $key)
           This family of methods provides a btree data structure for use by
           hashes.

           mm_make_btree_table allocates the data structure.

           mm_clear_btree_table clears the data structure, making it empty.

           mm_free_btree_table frees the data structure.

           mm_btree_table_get returns the value associated with $key.

           mm_btree_table_insert inserts a new entry into the btree, with $key
           equal to $val.

           mm_btree_table_delete deletes the entry in the btree identified by
           $key.

           mm_btree_table_exists tests for the existence of an entry in the
           btree identified by $key.

           mm_btree_table_first_key returns the first key in the btree.

           mm_btree_table_next_key returns the next key after $key in the
           btree.

           It is possible to tie a btree to a hash, like so:

             tie %tied_hash, 'IPC::MM::BTree', $btree;

           One interesting characteristic of the btree is that it is pre-
           sorted, so keys %tied_hash will return a sorted list of items.

       $hash = mm_make_hash($mm)
       mm_hash_clear($hash)
       mm_free_hash($hash)
       $val = mm_hash_get($hash, $key)
       $rc = mm_hash_insert($hash, $key, $val)
       $oldval = mm_hash_delete($hash, $key)
       $rc = mm_hash_exists($hash, $key)
       $key = mm_hash_first_key($hash)
       $key = mm_hash_next_key($hash, $key)
           This family of methods implements a shared memory hash list. These
           hash lists are not presorted like btrees, but they can be faster
           than btrees (especially unbalanced btrees).

           mm_make_hash allocates the data structure.

           mm_clear_hash clears the data structure, making it empty.

           mm_free_hash frees the data structure.

           mm_hash_get returns the value associated with $key.

           mm_hash_insert inserts a new entry into the hash, with $key equal
           to $val.

           mm_hash_delete deletes the entry in the hash identified by $key.

           mm_hash_exists tests for the existence of an entry in the hash
           identified by $key.

           mm_hash_first_key returns the first key in the hash.

           mm_hash_next_key returns the next key after $key in the hash.

           It is possible to tie a shared-memory hash to a perl hash, like so:

             tie %tied_hash, 'IPC::MM::Hash', $hash;

       $rc = mm_lock($mm, $mode)
           This method locks the shared memory pool $mm for the current
           process in order to perform either shared/read-only (mode
           MM_LOCK_RD) or exclusive/read-write (mode MM_LOCK_RW) operations.

       $rc = mm_unlock($mm)
           This method unlocks the shared memory pool $mm.

       $num = mm_maxsize
           This method returns the maximum allowable size for a shared memory
           segment.  It corresponds to the function of the same name in the mm
           library.

       $num = mm_available($mm)
           This method returns the number of free bytes left in a shared mem-
           ory segment.  It corresponds to the function of the same name in
           the mm library.

           $mm is a shared memory segment created by mm_create.

       $errstr = mm_error
           This method returns an error string, if any. It corresponds to the
           function of the same name in mm.

       mm_display_info($mm)
           This method displays some miscellaneous information about a shared
           memory segment. It corresponds to the function of the same name in
           mm.


BUGS

       No effort is made to balance the btree.


AUTHOR

       Copyright (c) 1999, Arthur Choung <arthur@etoys.com>.  All rights
       reserved.

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


SEE ALSO

       mm, IPC::Shareable, perl.

       perl(1).

perl v5.8.8                       2000-08-11                             MM(3)
See also IPC::Msg(3)
See also IPC::Open2(3)
See also IPC::Open3(3)
See also IPC::Semaphore(3)
See also IPC::ShareLite(3)
See also IPC::SysV(3)

Man(1) output converted with man2html