Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
forks::shared(3)      User Contributed Perl Documentation     forks::shared(3)

NAME
       forks::shared - drop-in replacement for Perl threads::shared with
       forks()

SYNOPSIS
	 use forks;
	 use forks::shared;

	 my $variable :	shared;
	 my @array    :	shared;
	 my %hash     :	shared;

	 share(	$variable );
	 share(	@array );
	 share(	%hash );

	 $variable = shared_clone($non_shared_ref_value);
	 $variable = shared_clone({'foo' => [qw/foo bar	baz/]});

	 lock( $variable );
	 cond_wait( $variable );
	 cond_wait( $variable, $lock_variable );
	 cond_timedwait( $variable, abs	time );
	 cond_timedwait( $variable, abs	time, $lock_variable );
	 cond_signal( $variable	);
	 cond_broadcast( $variable );

	 bless(	$variable, class name );

	 # Enable deadlock detection and resolution
	 use forks::shared deadlock => {
	   detect => 1,
	   resolve => 1
	 );
	 # or
	 threads::shared->set_deadlock_option(
	   detect  => 1,
	   resolve => 1
	 );

DESCRIPTION
       The "forks::shared" pragma allows a developer to	use shared variables
       with threads (implemented with the "forks" pragma) without having to
       have a threaded perl, or	to even	run 5.8.0 or higher.

       "forks::shared" is currently API	compatible with	CPAN threads::shared
       version 1.05.

EXPORT
       "share",	"shared_clone",	"cond_wait", "cond_timedwait", "cond_signal",
       "cond_broadcast", "is_shared", "bless"

       See "EXPORT" in threads::shared for more	information.

OBJECTS
       forks::shared exports a version of bless() that works on	shared
       objects,	such that blessings propagate across threads.  See
       threads::shared for usage information and the forks test	suite for
       additional examples.

EXTRA FEATURES
   Deadlock detection and resolution
       In the interest of helping programmers debug one	of the most common
       bugs in threaded	application software, forks::shared supports a full
       deadlock	detection and resolution engine.

       Automated detection and resolution

       There are two ways to enable these features: either at import time in a
       use statement, such as:

	   use forks::shared deadlock => { OPTIONS }

       or during runtime as a class method call	to "set_deadlock_option",
       like:

	   forks::shared->set_deadlock_option( OPTIONS );
	   #or
	   threads::shared->set_deadlock_option( OPTIONS );

       where "OPTIONS" may be a	combination of any of the following:

	   detect	  => 1 (enable)	or 0 (disable)
	   period	  => number of seconds between asynchronous polls
	   resolve	  => 1 (enable)	or 0 (disable)

       The "detect" option enables deadlock detection.	By itself, this	option
       enabled synchronous deadlock detection, which efficiently checks	for
       potential deadlocks at lock() time.  If any are detected	and warnings
       are enabled, it will print out details to "STDERR" like the following
       example:

	   Deadlock detected:
	       TID   SV	LOCKED	 SV LOCKING   Caller
		 1	     3		  4   t/forks06.t at line 41
		 2	     4		  3   t/forks06.t at line 46

       The "period" option, if set to a	value greater than zero, is the	number
       of seconds between asynchronous deadlock	detection checks.
       Asynchronous detection is useful	for debugging rare, time-critical race
       conditions leading to deadlocks that may	be masked by the slight	time
       overhead	introduced by synchronous detection on each lock() call.
       Overall,	it is less CPU intensive than synchronous deadlock detection.

       The "resolve" option enables auto-termination of	one thread in each
       deadlocked thread pair that has been detected.  As with the "detect"
       option, "resolve" prints	out the	action it performs to STDERR, if
       warnings	are enabled.  NOTE: "resolve" uses SIGKILL to break deadlocks,
       so this feature should not be used in environments where	stability of
       the rest	of your	application may	be adversely affected by process death
       in this manner.

       For example:

	   use forks;
	   use forks::shared
	       deadlock	=> {detect=> 1,	resolve	=> 1};

       Manual detection

       If you wish to check for	deadlocks without enabling automated deadlock
       detection, forks	provides an additonal thread object method,

	   $thr->is_deadlocked()

       that reports whether the	thread in question is currently	deadlocked.
       This method may be used in conjunction with the "resolve" deadlock
       option to auto-terminate	offending threads.

   Splice on shared array
       As of at	least threads::shared 1.05, the	splice function	has not	been
       implememted for arrays; however,	forks::shared fully supports splice on
       shared arrays.

   share() doesn't lose	value for arrays and hashes
       In the standard Perl threads implementation, arrays and hashes are re-
       initialized when	they become shared (with the share()) function.	 The
       share() function	of forks::shared does not initialize arrays and	hashes
       when they become	shared with the	share()	function.

       This could be considered	a bug in the standard Perl implementation.  In
       any case	this is	an inconsistency of the	behaviour of threads.pm	and
       forks.pm.

       If you do not have a natively threaded perl and you have	installed and
       are using forks in "threads.pm" override	mode (where "use threads"
       loads forks.pm),	then this module will explicitly emulate the behavior
       of standard threads::shared and lose value for arrays and hashes	with
       share().	 Additionally, array splice function will become a no-op with
       a warning.

       You may also enable this	mode by	setting	the environment	variable
       "THREADS_NATIVE_EMULATION" to a true value before running your script.
       See "Native threads 'to-the-letter' emulation mode" in forks for	more
       information.

CAVIATS
       Some caveats that you need to be	aware of.

       Storing CODE refs in shared variables
	 Since forks::shared requires Storable to serialize shared data
	 structures, storing CODE refs in shared variables is not enabled by
	 default (primarily for	security reasons).

	 If need share CODE refs between threads, the minimum you must do
	 before	storing	CODE refs is:

	     $Storable::Deparse	= $Storable::Eval = 1;

	 See "CODE_REFERENCES" in Storable for detailed	information, including
	 potential security risks and ways to protect yourself against them.

       test-suite exits	in a weird way
	 Although there	are no errors in the test-suite, the test harness
	 sometimes thinks there	is something wrong because of an unexpected
	 exit()	value.	This is	an issue with Test::More's END block, which
	 wasn't	designed to co-exist with a threads environment	and forked
	 processes.  Hopefully,	that module will be patched in the future, but
	 for now, the warnings are harmless and	may be safely ignored.

CURRENT	AUTHOR AND MAINTAINER
       Eric Rybski <rybskej@yahoo.com>.	 Please	send all module	inquries to
       me.

ORIGINAL AUTHOR
       Elizabeth Mattijsen, <liz@dijkmat.nl>.

COPYRIGHT
       Copyright (c)
	2005-2014 Eric Rybski <rybskej@yahoo.com>,
	2002-2004 Elizabeth Mattijsen <liz@dijkmat.nl>.	 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
       threads::shared,	forks, forks::BerkeleyDB::shared.

perl v5.32.0			  2014-06-27		      forks::shared(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORT | OBJECTS | EXTRA FEATURES | CAVIATS | CURRENT AUTHOR AND MAINTAINER | ORIGINAL AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=forks::shared&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help