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, allowing memory to be shared between multiple processes in a relatively convenient 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 interface 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 underlying 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 presorted, 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 memory 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).