lib/Thread/Cleanup.pm

   1 package Thread::Cleanup;
   2
   3 use 5.008;
   4
   5 use strict;
   6 use warnings;
   7
   8 =head1 NAME
   9
  10 Thread::Cleanup - Hook thread destruction.
  11
  12 =head1 VERSION
  13
  14 Version 0.06
  15
  16 =cut
  17
  18 our $VERSION;
  19
  20 BEGIN {
  21  $VERSION = '0.06';
  22  require XSLoader;
  23  XSLoader::load(__PACKAGE__, $VERSION);
  24 }
  25
  26 =head1 SYNOPSIS
  27
  28     use Thread::Cleanup;
  29
  30     use threads;
  31
  32     Thread::Cleanup::register {
  33      my $tid = threads->tid();
  34      warn "Thread $tid finished\n";
  35     };
  36
  37 =head1 DESCRIPTION
  38
  39 This module allows you to hook thread destruction without fiddling with the internals of L<threads>.
  40
  41 It acts globally on all the threads that may spawn anywhere in your program, with the exception of the main thread.
  42
  43 The hooks registered with this module will also be called when pseudo-forks (i.e. processes spawn on Windows for the C<fork> emulation) terminate.
  44
  45 =head1 FUNCTIONS
  46
  47 =head2 C<register>
  48
  49     register { ... };
  50     &register($coderef);
  51
  52 Specify that the given block or code reference C<$coderef> will have to be called (in void context, without arguments) every time a thread or a pseudo-fork terminates.
  53 More precisely :
  54
  55 =over 4
  56
  57 =item *
  58
  59 For joined threads, it will be called when C<join> succeeds, after any C<END> block local to the spawn thread ;
  60
  61 =item *
  62
  63 For detached threads, it will be called if and only if the thread terminates before the main thread, and the hook will then fire at global C<END> time ;
  64
  65 =item *
  66
  67 For pseudo-forks, it will be called when C<waitpid> succeeds, after any local or global C<END> block ;
  68
  69 =item *
  70
  71 It will never trigger for the destruction of the main thread.
  72
  73 =back
  74
  75 =cut
  76
  77 my @callbacks;
  78
  79 sub register (&) { push @callbacks, shift }
  80
  81 sub _CLEANUP { $_->() for @callbacks }
  82
  83 =head1 EXPORT
  84
  85 None.
  86
  87 =head1 DEPENDENCIES
  88
  89 L<perl> 5.8.
  90
  91 A C compiler.
  92 This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
  93
  94 L<threads> 1.07.
  95
  96 L<XSLoader>.
  97
  98 =head1 AUTHOR
  99
 100 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 101
 102 =head1 BUGS
 103
 104 Please report any bugs or feature requests to C<bug-thread-cleanup at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Thread-Cleanup>.  I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 105
 106 =head1 SUPPORT
 107
 108 You can find documentation for this module with the perldoc command.
 109
 110     perldoc Thread::Cleanup
 111
 112 =head1 ACKNOWLEDGEMENTS
 113
 114 Inspired by a question from TonyC on #p5p.
 115
 116 =head1 COPYRIGHT & LICENSE
 117
 118 Copyright 2009,2010,2013,2014 Vincent Pit, all rights reserved.
 119
 120 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 121
 122 =cut
 123
 124 1; # End of Thread::Cleanup