Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Thread::Bless
make blessed objects thread-aware

Thread::Bless - make blessed objects thread-aware


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 the register manpage 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 the Test::Harness manpage 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>.

Please report bugs to <perlbugs@dijkmat.nl>.


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, the mod_perl manpage.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy