view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    applications) or current working directory.

    This module handles all shared memory interaction via the
    IPC::SharedLite and all data serialization with Storable. See the
    IPC::ShareLite manpage and the Storable manpage for details.

USAGE
    If you are running under mod_perl, you should put this line in your
    httpd.conf:

        # must be a valid path
        PerlAddVar PROJECT_DOCUMENT_ROOT /path/to/your/projects/root

    and in your startup.pl:

        use Apache::SharedMem;

    This allow Apache::SharedMem to determine a unique rootkey for all
    virtual hosts, and to cleanup this rootkey on Apache stop.
    PROJECT_DOCUMENT_ROOT is used instead of a per virtal host's
    DOCUMENT_ROOT for rootkey's generation.

    You can also provide a PROJECT_ID, it's the server's uid by default.
    This value have to be numeric:

        PerlAddVar PROJECT_ID 10

METHODS
  new  (namespace => 'Namespace', ipc_mode => 0666, ipc_segment_size => 1_000, debug => 1)

    *   "rootkey" optional, integer

        Changes the root segment key. It must be an unsigned integer. Don't
        use this option unless you really know what you are doing.

        This key allows Apache::SharedMem to find the root map of all
        namespaces (see below) owned by your application.

        The rootkey is automatically generated using the "ftok" provided by
        IPC::SysV. Process' UID and DOCUMENT_ROOT (or current working
        directory) are given to "ftok" so as to guarantee an unique key as
        far as possible.

        Note, if you are using mod_perl, and you'v load mod_perl via
        startup.pl (see USAGE section for more details), the rootkey is
        generated once at the apache start, based on the supplied
        PROJECT_DOCUMENT_ROOT and Apache's uid.

    *   "namespace" optional, string

        Setup manually the namespace. To share same datas, your program must
        use the same namespace. This namespace is set by default to the
        caller's package name. In most cases the default value is a good
        choice. But you may setup manually this value if, for example, you
        want to share the same datas between two or more modules.

    *   "ipc_mode" optional, octal

        Setup manually the segment mode (see the IPC::ShareLite manpage) for
        more details (default: 0600). Warning: this value _must_ be octal,
        see chmod documentation in perlfunc manpage for more details.

    *   "ipc_segment_size" optional, integer

        Setup manually the segment size (see the IPC::ShareLite manpage) for
        more details (default: 65_536).

    *   "debug" optional, boolean

        Turn on/off the debug mode (default: 0)

    In most case, you don't need to give any arguments to the constructor.

    "ipc_mode" and "ipc_segment_size" are used only on the first namespace
    initialisation. Using different values on an existing key (in shared
    memory) has no effect.

    Note that "ipc_segment_size" is default value of IPC::ShareLite, see the
    IPC::ShareLite manpage

    On succes return an Apache::SharedMem object, on error, return undef().
    You can get error string via $Apache::SharedMem::ERROR.

  get  (key, [wait, [timeout]])

    my $var = $object->get('mykey', WAIT, 50); if($object->status & FAILURE)
    { die("can't get key 'mykey´: " . $object->error); }

    *   "key" required, string

        This is the name of elemenet that you want get from the shared
        namespace. It can be any string that perl support for hash's key.

    *   "wait" optional

        Defined the locking status of the request. If you must get the
        value, and can't continue without it, set this argument to constant
        WAIT, unless you can set it to NOWAIT.

        If the key is locked when you are tring to get the value, NOWAIT
        return status FAILURE, and WAIT hangup until the value is unlocked.
        An alternative is to setup a WAIT timeout, see below.

        NOTE: you needs :wait tag import:

            use Apache::SharedMem qw(:wait)

        timeout (optional) integer:

        if WAIT is on, timeout setup the number of seconds to wait for a
        blocking lock, usefull for preventing dead locks.

    Following status can be set (needs :status tag import):

    SUCCESS FAILURE

    On error, method return undef(), but undef() is also a valid answer, so
    don't test the method status by this way, use ($obj->status & SUCCESS)
    instead.

  set  (key, value, [wait, [timeout]])