NAME

forks::BerkeleyDB - high-performance drop-in replacement for threads

VERSION

This documentation describes version 0.06.

SYNOPSYS

  use forks::BerkeleyDB;

  my $thread = threads->new( sub {       # or ->create or async()
    print "Hello world from a thread\n";
  } );

  $thread->join;

  threads->detach;
  $thread->detach;

  my $tid    = $thread->tid;
  my $owntid = threads->tid;

  my $self    = threads->self;
  my $threadx = threads->object( $tidx );

  threads->yield();

  $_->join foreach threads->list;

  unless (fork) {
    threads->isthread; # intended to be used in a child-init Apache handler
  }

  use forks qw(debug);
  threads->debug( 1 );

  perl -Mforks::BerkeleyDB -Mforks::BerkeleyDB::shared threadapplication

DESCRIPTION

forks::BerkeleyDB is a drop-in replacement for threads, written as an extension of forks. The goal of this module is to improve upon the core performance of forks at a level comparable to native ithreads.

REQUIRED MODULES

 BerkeleyDB (0.27)
 Devel::Required (0.07)
 forks (0.29)
 Storable (any)
 Tie::Restore (0.11)

USAGE

See forks for common usage information.

Environment Variables

forks::BerkeleyDB supports several environment variables.

TMPDIR

forks::BerkeleyDB requires a temporary directory to store all BerkeleyDB environment and database files. This variable is controlled by File::Spec, so the default location for such files (in the case that TMPDIR is unset) will depend on your platform; e.g. File::Spec::Unix checks $ENV{TMPDIR} (unless taint is on) and /tmp.

THREADS_BDB_ENV_CHMOD

Sets the default file and directory permissions of BerkeleyDB environment and database files. If unset, will use the Perl default; e.g. current process (thread) umask with defaults for mkdir and open.

THREADS_BDB_ENV_CHOWN

Sets the default group owner of BerkeleyDB environment and database files. If unset, will use the Perl default; e.g. current process (thread) effective user.

THREADS_BDB_ENV_CHGRP

Sets the default group owner of BerkeleyDB environment and database files. If unset, will use the Perl default; e.g. current process (thread) effective group.

NOTES

All database files created during runtime will be automatically purged when the main thread exits. If you have created a large number of shared variables, you may experience a slight delay during process exit. Note that these files may not be cleaned up if the main thread or process group is terminated using SIGKILL, although existance of these files after exit should not have an adverse affect on other currently running or future forks::BerkeleyDB processes.

Testing has been performed against BerkeleyDB 4.3.x. Full compatibility is expected with BDB 4.x and likely with 3.x as well. Unclear if all tie methods are compatible with 2.x. This module is currently not compatible with BDB 1.x.

CAVIATS

This module defines CORE::GLOBAL::fork to insure BerkeleyDB resources are correctly managed before and after a fork occurs. This insures that processes will be able to safely use threads->isthread. You may encounter issues with your application or other modules it uses also define CORE::GLOBAL::fork. To work around this, you should modify your CORE::GLOBAL::fork to support chaining, like the following

        use subs 'fork';
        *_oldfork = \&CORE::GLOBAL::fork;
        sub fork {
                #your code here
                ...
                _oldfork->() if ref(*oldfork) eq 'SUB';
        }

TODO

See the TODO file in the distribution.

AUTHOR

Eric Rybski <rybskej@yahoo.com>.

COPYRIGHT

Copyright (c) 2006-2009 Eric Rybski <rybskej@yahoo.com>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

forks, threads

cpanm forks::BerkeleyDB

perl -MCPAN -e shell
install forks::BerkeleyDB