.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "forks::shared 3pm" .TH forks::shared 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME forks::shared \- drop\-in replacement for Perl threads::shared with forks() .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& 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({\*(Aqfoo\*(Aq => [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 \& ); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" The \f(CW\*(C`forks::shared\*(C'\fR 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. .PP \&\f(CW\*(C`forks::shared\*(C'\fR is currently API compatible with CPAN threads::shared version \f(CW1.05\fR. .SH EXPORT .IX Header "EXPORT" \&\f(CW\*(C`share\*(C'\fR, \f(CW\*(C`shared_clone\*(C'\fR, \f(CW\*(C`cond_wait\*(C'\fR, \f(CW\*(C`cond_timedwait\*(C'\fR, \f(CW\*(C`cond_signal\*(C'\fR, \&\f(CW\*(C`cond_broadcast\*(C'\fR, \f(CW\*(C`is_shared\*(C'\fR, \f(CW\*(C`bless\*(C'\fR .PP See "EXPORT" in threads::shared for more information. .SH OBJECTS .IX Header "OBJECTS" forks::shared exports a version of \fBbless()\fR 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. .SH "EXTRA FEATURES" .IX Header "EXTRA FEATURES" .SS "Deadlock detection and resolution" .IX Subsection "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. .PP \fIAutomated detection and resolution\fR .IX Subsection "Automated detection and resolution" .PP There are two ways to enable these features: either at import time in a use statement, such as: .PP .Vb 1 \& use forks::shared deadlock => { OPTIONS } .Ve .PP or during runtime as a class method call to \f(CW\*(C`set_deadlock_option\*(C'\fR, like: .PP .Vb 3 \& forks::shared\->set_deadlock_option( OPTIONS ); \& #or \& threads::shared\->set_deadlock_option( OPTIONS ); .Ve .PP where \f(CW\*(C`OPTIONS\*(C'\fR may be a combination of any of the following: .PP .Vb 3 \& detect => 1 (enable) or 0 (disable) \& period => number of seconds between asynchronous polls \& resolve => 1 (enable) or 0 (disable) .Ve .PP The \f(CW\*(C`detect\*(C'\fR option enables deadlock detection. By itself, this option enabled synchronous deadlock detection, which efficiently checks for potential deadlocks at \fBlock()\fR time. If any are detected and warnings are enabled, it will print out details to \f(CW\*(C`STDERR\*(C'\fR like the following example: .PP .Vb 4 \& 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 .Ve .PP The \f(CW\*(C`period\*(C'\fR 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 \fBlock()\fR call. Overall, it is less CPU intensive than synchronous deadlock detection. .PP The \f(CW\*(C`resolve\*(C'\fR option enables auto-termination of one thread in each deadlocked thread pair that has been detected. As with the \f(CW\*(C`detect\*(C'\fR option, \f(CW\*(C`resolve\*(C'\fR prints out the action it performs to STDERR, if warnings are enabled. \&\fBNOTE\fR: \f(CW\*(C`resolve\*(C'\fR 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. .PP For example: .PP .Vb 3 \& use forks; \& use forks::shared \& deadlock => {detect=> 1, resolve => 1}; .Ve .PP \fIManual detection\fR .IX Subsection "Manual detection" .PP If you wish to check for deadlocks without enabling automated deadlock detection, forks provides an additonal thread object method, .PP .Vb 1 \& $thr\->is_deadlocked() .Ve .PP that reports whether the thread in question is currently deadlocked. This method may be used in conjunction with the \f(CW\*(C`resolve\*(C'\fR deadlock option to auto-terminate offending threads. .SS "Splice on shared array" .IX Subsection "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. .SS "\fBshare()\fP doesn't lose value for arrays and hashes" .IX Subsection "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 \fBshare()\fR) function. The \&\fBshare()\fR function of forks::shared does \fBnot\fR initialize arrays and hashes when they become shared with the \fBshare()\fR function. .PP This \fBcould\fR 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. .PP 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 \fBshare()\fR. Additionally, array splice function will become a no-op with a warning. .PP You may also enable this mode by setting the environment variable \&\f(CW\*(C`THREADS_NATIVE_EMULATION\*(C'\fR to a true value before running your script. See "Native threads 'to\-the\-letter' emulation mode" in forks for more information. .SH CAVIATS .IX Header "CAVIATS" Some caveats that you need to be aware of. .IP "Storing CODE refs in shared variables" 2 .IX Item "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). .Sp If need share CODE refs between threads, the minimum you must do before storing CODE refs is: .Sp .Vb 1 \& $Storable::Deparse = $Storable::Eval = 1; .Ve .Sp See "CODE_REFERENCES" in Storable for detailed information, including potential security risks and ways to protect yourself against them. .IP "test-suite exits in a weird way" 2 .IX Item "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 \fBexit()\fR 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. .SH "CURRENT AUTHOR AND MAINTAINER" .IX Header "CURRENT AUTHOR AND MAINTAINER" Eric Rybski . Please send all module inquries to me. .SH "ORIGINAL AUTHOR" .IX Header "ORIGINAL AUTHOR" Elizabeth Mattijsen, . .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (c) 2005\-2014 Eric Rybski , 2002\-2004 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" threads::shared, forks, forks::BerkeleyDB::shared.