view release on metacpan or  search on metacpan

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

    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

=head2 new

This instantiates a shared memory object. It takes the following parameters:

=over 4

=item C<debug>

A debug value will enable debugging output (equal or above 3 actually)

=item C<create>

A boolean value to indicate whether the shared memory block should be created if it does not exist. Default to false.

=item C<destroy>

A boolean value to indicate if the shared memory block should be removed when the object is destroyed. See L<perlmod> for more about object destruction.

=item C<exclusive>

A boolean value to set the shared memory as exclusive. This will affect the flags set by L</flags> which are used by L</open>.

=item C<key>

The shared memory key identifier to use. It defaults to C<IPC::SysV::IPC_PRIVATE>

If you provide an empty value, it will revert to C<IPC::SysV::IPC_PRIVATE>.

If you provide a number, it will be used to call L<IPC::SysV/ftok>.

Otherwise, if you provide a key as string, the characters in the string will be converted to their numeric value and added up. The resulting id, called C<project id> by L<IPC::SysV>, will be used to call L<IPC::SysV/ftok> and will produce an hopefull...

Either way, the resulting value is used to create a shared memory segment and a semaphore by L</open>.

=item C<mode>

The octal mode value to use when opening the shared memory block.

Shared memory are owned by system users and access to shared memory segment is ruled by the initial permissions set to it.

If you do not want to share it with any other user than yourself, setting mode to C<0600> is fine.

=item C<size>

The size in byte of the shared memory.

This is set once it is created. You can create again the shared memory segment with a smaller size, but not a bigger one. If you want to increase the size, you would need to remove it first.

=back

An object will be returned if it successfully initiated, or undef() upon error, which can then be retrieved with C<Apache2::SSI::SharedMem->error>. You should always check the return value of the methods used here for their definedness.

    my $shmem = Apache2::SSI::SharedMem->new(
        create => 1,
        destroy => 0,