use strict;
use warnings;
-our $VERSION = '1.24_01';
+our $VERSION = '1.27';
my $XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
}
}
+
# Load the XS code
require XSLoader;
XSLoader::load('threads', $XS_VERSION);
# Handle args
while (my $sym = shift) {
- if ($sym =~ /all/) {
+ if ($sym =~ /^stack/) {
+ threads->set_stack_size(shift);
+
+ } elsif ($sym =~ /all/) {
push(@EXPORT, qw(yield));
} else {
no strict 'refs';
*{$caller.'::'.$sym} = \&{$sym};
}
+
+ # Set stack size via environment variable
+ if (exists($ENV{'PERL5_ITHREADS_STACK_SIZE'})) {
+ threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'});
+ }
}
=head1 VERSION
-This document describes threads version 1.24
+This document describes threads version 1.27
=head1 SYNOPSIS
- use threads ('yield');
+ use threads ('yield', 'stack_size' => 64*4096);
sub start_thread {
my @args = @_;
...
}
+ $stack_size = threads->get_stack_size();
+ $old_size = threads->set_stack_size(32*4096);
+
+ $thr->kill('SIGUSR1');
+
=head1 DESCRIPTION
-Perl 5.6 introduced something called interpreter threads. Interpreter
-threads are different from "5005threads" (the thread model of Perl
-5.005) by creating a new perl interpreter per thread and not sharing
-any data or state between threads by default.
+Perl 5.6 introduced something called interpreter threads. Interpreter threads
+are different from I<5005threads> (the thread model of Perl 5.005) by creating
+a new Perl interpreter per thread, and not sharing any data or state between
+threads by default.
-Prior to perl 5.8 this has only been available to people embedding
-perl and for emulating fork() on windows.
+Prior to Perl 5.8, this has only been available to people embedding Perl, and
+for emulating fork() on Windows.
-The threads API is loosely based on the old Thread.pm API. It is very
-important to note that variables are not shared between threads, all
-variables are per default thread local. To use shared variables one
-must use threads::shared.
+The I<threads> API is loosely based on the old Thread.pm API. It is very
+important to note that variables are not shared between threads, all variables
+are by default thread local. To use shared variables one must use
+L<threads::shared>.
-It is also important to note that you must enable threads by doing
-C<use threads> as early as possible in the script itself and that it
-is not possible to enable threading inside an C<eval "">, C<do>,
-C<require>, or C<use>. In particular, if you are intending to share
-variables with threads::shared, you must C<use threads> before you
-C<use threads::shared> and C<threads> will emit a warning if you do
-it the other way around.
+It is also important to note that you must enable threads by doing C<use
+threads> as early as possible in the script itself, and that it is not
+possible to enable threading inside an C<eval "">, C<do>, C<require>, or
+C<use>. In particular, if you are intending to share variables with
+L<threads::shared>, you must C<use threads> before you C<use threads::shared>.
+(C<threads> will emit a warning if you do it the other way around.)
=over
=back
+=head1 THREAD STACK SIZE
+
+The default per-thread stack size for different platforms varies
+significantly, and is almost always far more than is needed for most
+applications. On Win32, Perl's makefile explicitly sets the default stack to
+16 MB; on most other platforms, the system default is used, which again may be
+much larger than is needed.
+
+By tuning the stack size to more accurately reflect your application's needs,
+you may significantly reduce your application's memory usage, and increase the
+number of simultaneously running threads.
+
+N.B., on Windows, Address space allocation granularity is 64 KB, therefore,
+setting the stack smaller than that on Win32 Perl will not save any more
+memory.
+
+=over
+
+=item threads->get_stack_size();
+
+Returns the current default per-thread stack size. The default is zero, which
+means the system default stack size is currently in use.
+
+=item $size = $thr->get_stack_size();
+
+Returns the stack size for a particular thread. A return value of zero
+indicates the system default stack size was used for the thread.
+
+=item $old_size = threads->set_stack_size($new_size);
+
+Sets a new default per-thread stack size, and returns the previous setting.
+
+Some platforms have a minimum thread stack size. Trying to set the stack size
+below this value will result in a warning, and the minimum stack size will be
+used.
+
+Some Linux platforms have a maximum stack size. Setting too large of a stack
+size will cause thread creation to fail.
+
+If needed, C<$new_size> will be rounded up to the next multiple of the memory
+page size (usually 4096 or 8192).
+
+Threads created after the stack size is set will then either call
+C<pthread_attr_setstacksize()> I<(for pthreads platforms)>, or supply the
+stack size to C<CreateThread()> I<(for Win32 Perl)>.
+
+(Obviously, this call does not affect any currently extant threads.)
+
+=item use threads ('stack_size' => VALUE);
+
+This sets the default per-thread stack size at the start of the application.
+
+=item $ENV{'PERL5_ITHREADS_STACK_SIZE'}
+
+The default per-thread stack size may be set at the start of the application
+through the use of the environment variable C<PERL5_ITHREADS_STACK_SIZE>:
+
+ PERL5_ITHREADS_STACK_SIZE=1048576
+ export PERL5_ITHREADS_STACK_SIZE
+ perl -e'use threads; print(threads->get_stack_size(), "\n")'
+
+This value overrides any C<stack_size> parameter given to C<use threads>. Its
+primary purpose is to permit setting the per-thread stack size for legacy
+threaded applications.
+
+=item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
+
+This change to the thread creation method permits specifying the stack size
+for an individual thread.
+
+=item $thr2 = $thr1->create(FUNCTION, ARGS)
+
+This creates a new thread (C<$thr2>) that inherits the stack size from an
+existing thread (C<$thr1>). This is shorthand for the following:
+
+ my $stack_size = $thr1->get_stack_size();
+ my $thr2 = threads->create({'stack_size' => $stack_size}, FUNCTION, ARGS);
+
+=back
+
+=head1 THREAD SIGNALLING
+
+If Perl has been compiled to use safe signals (i.e., was not built with
+C<PERL_OLD_SIGNALS> - see C<perl -V>), then signals may be sent and acted upon
+by individual threads.
+
+=over 4
+
+=item $thr->kill('SIG...');
+
+Sends the specified signal to the thread. Signal names and (positive) signal
+numbers are the same as those supported by
+L<kill()|perlfunc/"kill SIGNAL, LIST">. For example, 'SIGTERM', 'TERM' and
+(depending on the OS) 15 are all valid arguments to C<-E<gt>kill()>.
+
+Returns the thread object to allow for method chaining:
+
+ $thr->kill('SIG...')->join();
+
+=back
+
+Signal handlers need to be set up in the threads for the signals they are
+expected to act upon. Here's an example for I<cancelling> a thread:
+
+ use threads;
+
+ # Suppress warning message when thread is 'killed'
+ no warnings 'threads';
+
+ sub thr_func
+ {
+ # Thread 'cancellation' signal handler
+ $SIG{'KILL'} = sub { die("Thread killed\n"); };
+
+ ...
+ }
+
+ # Create a thread
+ my $thr = threads->create('thr_func');
+
+ ...
+
+ # Signal the thread to terminate, and then detach
+ # it so that it will get cleaned up automatically
+ $thr->kill('KILL')->detach();
+
+Here's another example that uses a semaphore to provide I<suspend> and
+I<resume> capabilities:
+
+ use threads;
+ use Thread::Semaphore;
+
+ sub thr_func
+ {
+ my $sema = shift;
+
+ # Thread 'suspend/resume' signal handler
+ $SIG{'STOP'} = sub {
+ $sema->down(); # Thread suspended
+ $sema->up(); # Thread resumes
+ };
+
+ ...
+ }
+
+ # Create a semaphore and send it to a thread
+ my $sema = Thread::Semaphore->new();
+ my $thr = threads->create('thr_func', $sema);
+
+ # Suspend the thread
+ $sema->down();
+ $thr->kill('STOP');
+
+ ...
+
+ # Allow the thread to continue
+ $sema->up();
+
+CAVEAT: Sending a signal to a thread does not disrupt the operation the
+thread is currently working on: The signal will be acted upon after the
+current operation has completed. For instance, if the thread is I<stuck> on
+an I/O call, sending it a signal will not cause the I/O call to be interrupted
+such that the signal is acted up immediately.
+
=head1 WARNINGS
=over 4
=item A thread exited while # other threads were still running
-A thread (not necessarily the main thread) exited while there were
-still other threads running. Usually it's a good idea to first collect
-the return values of the created threads by joining them, and only then
-exit from the main thread.
+A thread (not necessarily the main thread) exited while there were still other
+threads running. Usually, it's a good idea to first collect the return values
+of the created threads by joining them, and only then exit from the main
+thread.
+
+=item Thread creation failed: pthread_create returned #
+
+See the appropriate I<man> page for C<pthread_create> to determine the actual
+cause for the failure.
+
+=item Thread # terminated abnormally: ...
+
+A thread terminated in some manner other than just returning from its entry
+point function. For example, the thread may have exited via C<die>.
+
+=item Using minimum thread stack size of #
+
+Some platforms have a minimum thread stack size. Trying to set the stack size
+below this value will result in the above warning, and the stack size will be
+set to the minimum.
+
+=item Thread creation failed: pthread_attr_setstacksize(I<SIZE>) returned 22
+
+The specified I<SIZE> exceeds the system's maximum stack size. Use a smaller
+value for the stack size.
=back
+If needed, thread warnings can be suppressed by using:
+
+ no warnings 'threads';
+
+in the appropriate scope.
+
=head1 ERRORS
=over 4
L<threads> module (i.e., threaded and non-threaded Perls are binary
incompatible.)
+=item Cannot change stack size of an existing thread
+
+The stack size of currently extant threads cannot be changed, therefore, the
+following results in the above error:
+
+ $thr->set_stack_size($size);
+
+=item Cannot signal other threads without safe signals
+
+The particular copy of Perl that you're trying to use was built using
+C<PERL_OLD_SIGNALS>. As a result, the C<-E<gt>kill()> signalling method
+cannot be used.
+
+=item Unrecognized signal name: ...
+
+The particular copy of Perl that you're trying to use does not support the
+specified signal being used in a C<-E<gt>kill()> call.
+
=back
=head1 BUGS
=item Creating threads inside BEGIN blocks
-Creating threads inside BEGIN blocks (or during the compilation phase
-in general) does not work. (In Windows, trying to use fork() inside
-BEGIN blocks is an equally losing proposition, since it has been
-implemented in very much the same way as threads.)
+Creating threads inside BEGIN blocks (or during the compilation phase in
+general) does not work. (In Windows, trying to use fork() inside BEGIN blocks
+is an equally losing proposition, since it has been implemented in very much
+the same way as threads.)
=item PERL_OLD_SIGNALS are not threadsafe, will not be.
-If your Perl has been built with PERL_OLD_SIGNALS (one has
-to explicitly add that symbol to ccflags, see C<perl -V>),
-signal handling is not threadsafe.
+If your Perl has been built with PERL_OLD_SIGNALS (one has to explicitly add
+that symbol to I<ccflags>, see C<perl -V>), signal handling is not threadsafe.
=item Returning closures from threads
L<http://www.cpanforum.com/dist/threads>
Annotated POD for L<threads>:
-L<http://annocpan.org/~JDHEDDEN/threads-1.24/shared.pm>
+L<http://annocpan.org/~JDHEDDEN/threads-1.27/shared.pm>
L<threads::shared>, L<perlthrtut>
Perl threads mailing list:
L<http://lists.cpan.org/showlist.cgi?name=iThreads>
+Stack size discussion:
+L<http://www.perlmonks.org/?node_id=532956>
+
=head1 AUTHOR
Artur Bergman E<lt>sky AT crucially DOT netE<gt>
Vipul Ved Prakash E<lt>mail AT vipul DOT netE<gt> -
Helping with debugging
+Dean Arnold E<lt>darnold AT presicient DOT comE<gt> -
+Stack size API
+
=cut
projects / p5sagit/p5-mst-13.2.git / blobdiff