Thread::Bless - make blessed objects thread-aware
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
*** 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.
These are the class methods.
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:
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.
If the value 1 is specified, then all objects will have the DESTROY method called on them when they are going out of scope.
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.
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.
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).
Scalar::Util (1.08)
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.
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.
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.
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.
"Attempt to free unreferenced scalar: SV 0xdeadbeef during global destruction."
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.
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.
Examples should be added.
Elizabeth Mattijsen, <liz@dijkmat.nl>.
maintained by LNATION, <email@lnation.org>.
Please report bugs to <email@lnation.org>.
Stas Bekman for the initial impetus, comments and suggestions.
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.
threads, mod_perl.
To install Thread::Bless, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Thread::Bless
CPAN shell
perl -MCPAN -e shell install Thread::Bless
For more information on module installation, please visit the detailed CPAN module installation guide.