/ 
Thread-Bless-0.09
River stage zero No dependents
/ Thread::Bless

NAME

Thread::Bless - make blessed objects thread-aware

SYNOPSIS

use Thread::Bless;     # make objects of this class thread-aware

use Thread::Bless      # for your own module
 destroy => 1,         # default: 0 = original thread only
 fixup   => 'subname', # default: undef = no special cloning
;

sub new { bless {},shift } # bless now thread aware for selected modules

Thread::Bless->destroy( 0|1 );       # set/adapt destroy setting
$destroy = Thread::Bless->destroy;   # obtain setting

Thread::Bless->fixup( \&fixup_sub ); # set/adapt fixup sub later
Thread::Bless->fixup( undef );       # disable fixup sub
$fixup = Thread::Bless->fixup;       # obtain setting

use Thread::Bless (        # provide settings for other packages
 package => 'Foo',                       # Foo
  fixup => sub { 'Fixup for Foo' },      # destroy => 0 implied
 package => 'Bar',                       # Bar, destroy => 0, no fixup
 package => [qw(Baz Baz::Boo Baz::Bee)], # listed modules
  destroy => 1,                          # destroy also in threads
  fixup => 'Baz::fixup',                 # call this sub for fixup
);

Thread::Bless->register( @object ); # for objects from XSUBs only

DESCRIPTION

                 *** A note of CAUTION ***

This module only functions on Perl versions 5.8.0 and later.
And then only when threads are enabled with -Dusethreads.  It
is of no use with any version of Perl before 5.8.0 or without
threads enabled.

                 *************************

This module adds two features to threads that are sorely missed by some.

The first feature is that the DESTROY method is called only on the object if the object is destroyed in the thread it was created in. This feature is automatically activated when Thread::Bless is used.

The second feature is that an optional fixup method is called on the object (automatically by Thread::Bless) just after the object is cloned (automatically by Perl) when a thread is started. This is needed if the object contains (references to) data structures that are not automatically handled by Perl.

Both features can be switched on/off seperately at compile or runtime to provide the utmost flexibility.

For external modules that need to be thread aware but aren't yet (most notably the ones that cannot handle having DESTROY called when cloned versions are destroyed in threads), you can also activate Thread::Bless on them.

CLASS METHODS

These are the class methods.

destroy

Thread::Bless->destroy( 0 );        # call DESTROY on original only

Thread::Bless->destroy( 1 );        # call DESTROY on all objects

$destroy = Thread::Bless->destroy;  # return current setting

The input parameter recognizes the following values:

original (0)

If the value 0 is specified, then only objects will have the DESTROY method called on them in the thread in which they were created. This is the default setting.

all (1)

If the value 1 is specified, then all objects will have the DESTROY method called on them when they are going out of scope.

fixup

Thread::Bless->fixup( undef );             # don't execute anything on cloning

Thread::Bless->fixup( 'fixup' );           # call 'fixup' as an object method

Thread::Bless->fixup( \&fixup );           # code reference is also ok

$fixup = Thread::Bless->fixup;             # return current code reference

The "fixup" class method sets and returns the subroutine that will be executed when an object of the class from which this class method is called.

initialize

Thread::Bless->initialize;  # only needed in special cases

The "initialize" class method is needed only in an environment where modules are loaded at runtime with "require" or "eval" (such as the MOD_PERL environment). It runs the initializations that are normally run automatically in "normal" Perl environments.

register

Thread::Bless->register( @object ); # only for blessed objects created in XSUBs

Not all blessed objects in Perl are necessarily created with "bless": they can also be created in XSUBs and thereby bypass the registration mechanism that Thread::Bless installs for "bless". For those cases, it is possible to register objects created in such a manner by calling the "register" class function. Any object passed to it will be registerd if the class of the object is a class for which Thread::Bless operates (either implicitely or explicitely have the "package" class method called for).

REQUIRED MODULES

Scalar::Util (1.08)

ORDER OF LOADING

The Thread::Bless module installs its own version of the "bless" system function. Without that special version of "bless", it can not work (unless you register your objects yourself). This means that the Thread::Bless module needs to be loaded before any modules that you want the special functionality of Thread::Bless to be applied to.

BUGS

None in the module itself (so far). However, several Perl versions have problems with cloned, weakened references (which are used by Thread::Bless to keep record of the objects that need fixing up and/or destroying). This shows up as errors in the test-suite or lots of warnings being displayed. Later versions of the Thread::Bless module may include XS code to circumvent these problems for specific versions of Perl.

Perl 5.8.0

Doesn't seem to handle weakened references at all: core dumps during the test-suite with "Bizarre SvTYPE [80]" error. It is not recommended to use Thread::Bless on this version of Perl (yet) and therefore you cannot easily install Thread::Bless with 5.8.0.

Perl 5.8.1

Issues warnings whenever a thread is shut down, one for each package that has Thread::Bless enabled on it:

"Attempt to free unreferenced scalar during global destruction."

So far, this warning does not seem to affect further execution of Perl. The test-suite should complete without finding any errors.

Perl 5.8.2, 5.8.3 and 5.9.0

Issues warnings whenever a thread is shut down, one for each package that has Thread::Bless enabled on it:

"Attempt to free unreferenced scalar: SV 0xdeadbeef during global destruction."

So far, this warning does not seem to affect further execution of Perl. The test-suite should complete without finding any errors.

Futhermore, some interaction with Test::Harness causes the warning:

Too late to run INIT block at .../Thread/Bless.pm line NNN.

to be displayed during testing. It does not seem to affect the outcome of the test. See also "MOD_PERL" for more information about INIT {} related issues.

MOD_PERL

This module's functioning depends on running the INIT {} subroutine automatically when Perl starts executing. However, this does not happen when running under mod_perl: the INIT state has passed long before this module is loaded, see

L<http://perl.apache.org/docs/1.0/guide/porting.html#CHECK_And_INIT_Blocks>

for more information. Therefore this module does not work correctly unless you execute this special initialization check yourself. This, fortunately, is easy to do, by adding:

Thread::Bless->initialize;

Executing the "initialize" class method is enough to do the initializations that Thread::Bless needs (provided Thread::Bless was loaded before any of the modules to which it should apply its magic). And to ensure full compatibility with this and future versions of this module, Perl and mod_perl, you can call this class method as many times as you want: only modules that have not been initialized before, will be initialized when this class method is executed.

TODO

Examples should be added.

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

maintained by LNATION, <email@lnation.org>.

Please report bugs to <email@lnation.org>.

ACKNOWLEDGEMENTS

Stas Bekman for the initial impetus, comments and suggestions.

COPYRIGHT

Copyright (c) 2003-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, mod_perl.