view release on metacpan or  search on metacpan

lib/Apache2/SSI/SharedMem.pod  view on Meta::CPAN

Apache2::SSI::SharedMem - Apache2 SSI Notes Shared Memory Manipulation

=head1 SYNOPSIS

    # Check if IPC::SysV is supported on this system
    if( Apache2::SSI::SharedMem->supported )
    {
        my $shmem = Apache2::SSI::SharedMem->new( key => 'some_identifier' ) ||
            die( Apache2::SSI::SharedMem->error );
    }
    
    my $shmem = Apache2::SSI::SharedMem->new(
        # Create if necessary, or re-use if already exists
        create => 1,
        # Self-destroy upon end of object. Default to false
        destroy => 0,
        # make access exclusive
        exclusive => 1,
        key => 'some_identifier',
        mode => 0666,
        # 100K
        size => 102400,
        debug => 3,
    ) || die( Apache2::SSI::SharedMem->error );

    # Check if it already exists
    if( $shmem->exists )
    {
        # do something
    }

    $shmem->create(0);
    $shmem->destroy(0);
    $shmem->exclusive(0);
    # Then get the bitwise flags based on those options set above:
    my $flags = $shmem->flags;
    # or specify overriding values:
    my $flags = $shmem->flags({
        create => 0,
        destroy => 0,
        exclusive => 0,
    });

    # Remove create bit
    use IPC::SysV qw( IPC_CREAT );
    $flags ^= IPC_CREAT;
    my $s = $shmem->open || die( $shmem->error );

    # Get the shared memory id
    my $id = $s->id;

    my $key = $s->key;

    # Get the actual key used in interacting with shared memory
    # You should not mess with this unless you know what you are doing
    my $shem_key = $s->serial;

    use Apache2::SSI::SharedMem qw( :all );
    $s->lock( LOCK_EX ) || die( $s->error );
    # Is it locked?
    my $is_locked = $s->locked;

    # example: 0666
    my $mode = $s->mode;
    my $s = $shmem->open || die( $shmem->error );

    # Actually the process pid
    my $owner = $s->owner;

    # The semaphore pid
    my $sempid = $s->pid;

    # Get a random key to use to create shared memory block
    my $random_key = $shmem->rand;

    my $data = $s->read;
    my $buffer;
    $s->read( $buffer );
    # or, if data is not a reference, trim data after 1024 bytes
    my $len = $s->read( $buffer, 1024 ) || die( $s->error );

    $s->remove;

    my $semaphore_id = $s->semid;

    # or $s->size;
    my $shared_mem_size = $shmem->size;

    # See Apache2::SSI::SemStat
    my $stat = $s->stat;

    # Remove lock
    $s->unlock;

    $s->write( $data ) || die( $s->error );

=head1 VERSION

    v0.1.2

=head1 DESCRIPTION

L<Apache2::SSI::SharedMem> provides an easy to use api to manipulate shared memory block. See L<perlipc> for more information.

As stipulated in L<perlport>, this is not supported on the following platforms: android, cygwin, dos, Microsoft Windows, OS2, VMS and Risc OS.

You can check if the system is supported with L</supported>

    if( Apache2::SSI::SharedMem->supported )
    {
        # do something
    }

=head1 DEBUGGING

To list all used shared memory, at least on Unix type systems such as Linux or FreeBSD (including MacOSX), use:

    ipcs -m

=head1 METHODS

lib/Apache2/SSI/SharedMem.pod  view on Meta::CPAN

=head2 destroy

Set or get the boolean value to indicate that the shared memory should be automatically destroyed when the module object is destroyed. See L<perlmod> for more information about module object destruction.

=head2 detach

Quoting the IPC documentation, this detaches the shared memory segment located at the address specified by L</attach> from this address space.

It returns C<undef> if it is not attached anymore, but without setting an error.

=head2 exclusive

Set or get the boolean value to affect the open flags in exclusive mode.

=head2 exists

Checks if the shared memory identified with C<key> exists.

It takes the same arguments as L</open> and returns 1 if the shared memory exists or 0 otherwise.

It does this by performing a L<perlfunc/shmget> such as:

    shmget( $shared_mem_key, $size, 0444 );

This will typically return the shared memory id if it exists or C<undef()> with an error set in C<$!> by perl otherwise.

=head2 flags

Provided with an optional hash or hash reference and this return a bitwise value of flags used by L</open>.

    my $flags = $shmem->flags({
        create => 1,
        exclusive => 0,
        mode => 0600,
    }) || die( $shmem->error );

=head2 id

Returns the id of the shared memory once it has been opened with L</open>

    my $s = $shmem->open || die( $shmem->error );
    my $id = $s->id;

=head2 key

Sets or gets the shared memory key identifier.

    $shem->key( 'some_identifier' );

=head2 lock

It takes an optional bitwise lock value, and defaults to C<LOCK_SH> if none is provided and issues a lock on the shared memory.

    use Apache2::SSI::SharedMem qw( :all );
    my $s = $shem->open || die( $shmem->error );
    $s->lock( LOCK_EX );
    # Do something
    $s->unlock;

=head2 locked

Returns a positive value when a lock is active or 0 when there is no active lock.

The value is the bitwise value of the lock used.

=head2 mode

Sets or gets the mode for the shared memory as used by L</open>

    $shmem->mode( 0666 );
    my $s = $shmem->open || die( $shmem->error );

=head2 op

Issue an opeation on the L<semaphore|https://en.wikipedia.org/wiki/Semaphore_(programming)>.

Provided value sould be a set of 3.

    ＄s->op( @{$Apache2::SSI::SharedMem->{(SEMOP_ARGS)}} ) ||
        die( $s->error );

=head2 open

Create an access to the shared memory and return a new L<Apache2::SSI::SharedMem> object.

    my $shmem = Apache2::SSI::SharedMem->new(
        create => 1,
        destroy => 0,
        # If not provided, will use the one provided during object instantiation
        key => 'my_memory',
        # 64K
        size => 65536,
    ) || die( Apache2::SSI::SharedMem->error );
    # Overriding some default value set during previous object instantiation
    my $s = $shmem->open({
        mode => 0600,
        size => 1024,
    }) || die( $shmem->error );

If the L</create> option is set to true, but the shared memory already exists, L</open> will detect it and attempt to open access to the shared memory without the L</create> bit on, which is C<IPC::SysV::IPC_CREAT>

=head2 owner

Sets or gets the shared memory owner, which is by default actually the process id (C<$$>)

=head2 pid

Get the L<semaphore|https://en.wikipedia.org/wiki/Semaphore_(programming)> pid once the shared memory has been opened.

    my $pid = $s->pid || die( $s->error );

=head2 rand

Get a random key to be used as identifier to create a shared memory.

=head2 read

Read the content of the shared memory.

You can optionally provide a buffer, and a maximum length and it will put the shared memory content in that buffer up to the maximum length, if it were provided.