view release on metacpan or  search on metacpan

lib/Apache/SharedMem.pm  view on Meta::CPAN

    $Apache::SharedMem::VERSION  = '0.09';
}

# main
{
    if(exists $ENV{'GATEWAY_INTERFACE'} && $ENV{'GATEWAY_INTERFACE'} =~ /^CGI-Perl/ 
        && defined $Apache::Server::Starting && $Apache::Server::Starting)
    {
        # we are under startup.pl
        if($Apache::SharedMem::ROOTKEY = _get_rootkey())
        {
            Apache->server->register_cleanup(\&Apache::SharedMem::_cleanup);
        }
        else
        {
            print(STDERR "Apache::SharedMem: can't determine the global root key, have you put 'PerlAddVar PROJECT_DOCUMENT_ROOT /path/to/your/project/root/' in your httpd.conf ?\n");
        }
    }
}

=pod

=head1 METHODS

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

=over 4

=item *

C<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 C<ftok> provided by IPC::SysV. 
Process' UID and DOCUMENT_ROOT (or current working directory) are given to C<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.

=item *

C<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. 

=item *

C<ipc_mode> optional, octal

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

=item *

C<ipc_segment_size> optional, integer

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

=item *

C<debug> optional, boolean

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

=back

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

C<ipc_mode> and C<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 C<ipc_segment_size> is default value of IPC::ShareLite, see
L<IPC::ShareLite> 

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

=cut

sub new 
{
    my $pkg = shift;
    my $self = bless({}, ref($pkg) || $pkg);

    my $options = $self->{options} =
    {
        rootname            => undef, # obsolete, use rootkey instead
        rootkey             => undef, # if not spécified, take the rootname value if exists or _get_rootkey()
        namespace           => (caller())[0],
        ipc_mode            => IPC_MODE,
        ipc_segment_size    => IPC_SEGSIZE,
        readonly            => 0,
        debug               => 0,
    };

    croak("odd number of arguments for object construction")
      if(@_ % 2);
    for(my $x = 0; $x <= $#_; $x += 2)
    {
        croak("Unknown parameter $_[$x] in $pkg object creation")
          unless(exists($options->{lc($_[$x])}));
        $options->{lc($_[$x])} = $_[($x + 1)];
    }

    _init_dumper() if($options->{debug});

    if($options->{rootname})
    {
        carp('obsolete parameter: rootname');
        # delete rootname parameter and if rootkey is undefined, copy the old rootname value in it.