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.05
  15
  16 =cut
  17
  18 our $VERSION;
  19
  20 BEGIN {
  21  $VERSION = '0.05';
  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 hook 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 C<END> block local to the spawn process but before any 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