Lines Matching defs:threads
1 package threads;
12 # Verify this Perl supports threads
15 die("This Perl not built to support threads\n");
18 # Complain if 'threads' is loaded after 'threads::shared'
19 if ($threads::shared::threads_shared) {
21 Warning, threads::shared has already been loaded. To
22 enable shared variables, 'use threads' must be called
23 before threads::shared or any module that uses it.
28 $threads::threads = 1;
32 XSLoader::load('threads', $XS_VERSION);
49 threads->set_stack_size($arg);
51 $threads::thread_exit_only = $arg =~ /^thread/i;
55 Carp::croak("threads: Missing argument for option: $sym");
66 Carp::croak("threads: Unknown import option: $sym");
79 threads->set_stack_size($ENV{'PERL5_ITHREADS_STACK_SIZE'});
97 Carp::croak('Usage: threads->exit(status)');
104 # 'Constant' args for threads->list()
105 sub threads::all { }
106 sub threads::running { 1 }
107 sub threads::joinable { 0 }
112 # 'async' is a function alias for the 'threads->create()' method
115 unshift(@_, 'threads');
133 threads - Perl interpreter-based threads
137 This document describes threads version 2.40
141 The "interpreter-based threads" provided by Perl are not the fast, lightweight
146 The use of interpreter-based threads in perl is officially
151 use threads ('yield',
160 my $thr = threads->create('start_thread', 'argument');
163 threads->create(sub { print("I am a thread\n"); })->join();
172 my ($thr) = threads->create(sub { return (qw/a b c/); });
174 my $thr = threads->create({'context' => 'list'},
181 $thr = threads->self();
182 $thr = threads->object($tid);
185 $tid = threads->tid();
189 # Give other threads a chance to run
190 threads->yield();
193 # Lists of non-detached threads
194 my @threads = threads->list();
195 my $thread_count = threads->list();
197 my @running = threads->list(threads::running);
198 my @joinable = threads->list(threads::joinable);
206 $stack_size = threads->get_stack_size();
207 $old_size = threads->set_stack_size(32*4096);
210 my $thr = threads->create({ 'context' => 'list',
230 threads->exit();
235 I<interpreter threads> which provides a new Perl interpreter for each
237 between threads.
239 (Prior to Perl 5.8, I<5005threads> was available through the C<Thread.pm> API.
243 variables, you need to also load L<threads::shared>:
245 use threads;
246 use threads::shared;
248 When loading L<threads::shared>, you must C<use threads> before you
249 C<use threads::shared>. (C<threads> will emit a warning if you do it the
252 It is strongly recommended that you enable threads via C<use threads> as early
258 my $can_use_threads = eval 'use threads; 1';
260 # Do processing using threads
263 # Do it without using threads
269 =item $thr = threads->create(FUNCTION, ARGS)
273 return the corresponding threads object, or C<undef> if thread creation failed.
278 my $thr = threads->create('func_name', ...);
280 my $thr = threads->create(sub { ... }, ...);
282 my $thr = threads->create(\&func, ...);
296 my ($thr1) = threads->create(sub {
301 my $thr1 = threads->create({'context' => 'list'},
310 my $thr2 = threads->create(sub {
318 my $thr3 = threads->create({'void' => 1},
325 If the program exits without all threads having either been joined or
334 discarded. When the program exits, any detached threads that are still
337 If the program exits without all threads having either been joined or
343 =item threads->detach()
347 =item threads->self()
349 Class method that allows a thread to obtain its own I<threads> object.
356 =item threads->tid()
362 If you add the C<stringify> import option to your C<use threads> declaration,
363 then using a threads object in a string or a string context (e.g., as a hash
366 use threads qw(stringify);
368 my $thr = threads->create(...);
371 =item threads->object($tid)
373 This will return the I<threads> object for the I<active> thread associated
379 =item threads->yield()
382 threads. What actually happens is highly dependent upon the underlying
385 You may do C<use threads qw(yield)>, and then just use C<yield()> in your
388 =item threads->list()
390 =item threads->list(threads::all)
392 =item threads->list(threads::running)
394 =item threads->list(threads::joinable)
396 With no arguments (or using C<threads::all>) and in a list context, returns a
397 list of all non-joined, non-detached I<threads> objects. In a scalar context,
400 With a I<true> argument (using C<threads::running>), returns a list of all
401 non-joined, non-detached I<threads> objects that are still running.
403 With a I<false> argument (using C<threads::joinable>), returns a list of all
404 non-joined, non-detached I<threads> objects that have finished running (i.e.,
409 Tests if two threads objects are the same thread or not. This is overloaded
426 semicolon after the closing brace. Like C<threads-E<gt>create()>, C<async>
427 returns a I<threads> object.
439 threads object. For Win32, this is a pointer to the C<HANDLE> value returned
444 This method is of no use for general Perl threads programming. Its intent is
449 =item threads->_handle()
463 =item threads->exit()
466 C<threads-E<gt>exit()>. This will cause the thread to return C<undef> in a
471 =item threads->exit(status)
473 When called from a thread, this behaves like C<threads-E<gt>exit()> (i.e., the
494 threads->exit() if threads->can('exit'); # Thread friendly
497 =item use threads 'exit' => 'threads_only'
501 C<threads-E<gt>exit()>. In other words, with this setting, calling C<exit()>
509 =item threads->create({'exit' => 'thread_only'}, ...)
523 =item threads->set_thread_exit_only(boolean)
553 =item threads->is_detached()
575 my $thr = threads->create({'context' => 'list'}, \&foo);
579 In the above, the threads object is returned to the parent thread in scalar
584 Similarly, if you need the threads object, but your thread will not be
587 my $thr = threads->create({'context' => 'void'}, \&foo);
594 threads->create({'scalar' => 1}, \&foo);
596 my ($thr) = threads->list();
605 my ($thr) = threads->create(...);
608 my $thr = threads->create(...);
611 threads->create(...);
618 =head2 threads->wantarray()
634 number of simultaneously running threads.
642 =item threads->get_stack_size();
652 =item $old_size = threads->set_stack_size($new_size);
670 (Obviously, this call does not affect any currently extant threads.)
672 =item use threads ('stack_size' => VALUE);
683 perl -e'use threads; print(threads->get_stack_size(), "\n")'
685 This value overrides any C<stack_size> parameter given to C<use threads>. Its
689 =item threads->create({'stack_size' => VALUE}, FUNCTION, ARGS)
694 my $thr = threads->create({'stack_size' => 32*4096},
703 my $thr2 = threads->create({'stack_size' => $stack_size},
712 threads.
729 Signal handlers need to be set up in the threads for the signals they are
732 use threads;
737 $SIG{'KILL'} = sub { threads->exit(); };
743 my $thr = threads->create('thr_func');
755 use threads;
773 my $thr = threads->create('thr_func', $sema);
807 =item Perl exited with active threads:
809 If the program exits without all threads having either been joined or
813 using C<no warnings 'threads';> as suggested below.
823 point function, or by using C<threads-E<gt>exit()>. For example, the thread
841 no warnings 'threads';
849 =item This Perl not built to support threads
854 Having threads support requires all of Perl and all of the XS modules in the
856 L<threads> module (i.e., threaded and non-threaded Perls are binary
861 The stack size of currently extant threads cannot be changed, therefore, the
866 =item Cannot signal threads without safe signals
913 C<-E<gt>import()>) after any threads are started, and in such a way that no
914 other threads are started afterwards.
921 On most systems, frequent and continual creation and destruction of threads
923 interpreter. While it is simple to just launch threads and then
925 better to maintain a pool of threads, and to reuse them for the work needed,
926 using L<queues|Thread::Queue> to notify threads of pending work. The CPAN
929 pool of I<reusable> threads.
934 is shared among all threads such that changing it in one thread (e.g., using
935 C<chdir()>) will affect all the threads in the application.
942 Prior to Perl 5.28, locales could not be used with threads, due to various
944 thread-safe locale functions, threads can be used, with some caveats.
957 and then pass to threads->create() a sub that closes over C<$foo>. Then, in
962 Or you can use the facilities in L<threads::shared> to pass C<$foo>;
970 C<system()> or back-ticks) made from threads use the environment variable
985 Therefore, setting up signal handlers in threads for purposes other than
990 alarms in threads, set up a signal handler in the main thread, and then use
994 my $thr = threads->create(sub {
995 threads->yield();
1012 =item Parent-child threads
1014 On some platforms, it might not be possible to destroy I<parent> threads while
1015 there are still existing I<child> threads.
1041 =item Identity of objects returned from threads
1059 =item Returning blessed objects from threads
1061 Returning blessed objects from threads does not work. Depending on the classes
1065 later, and if the class supports L<shared objects|threads::shared/"OBJECTS">,
1068 =item END blocks in threads
1071 END"> to threads by using L<require|perlfunc/"require VERSION"> or
1076 However, calling any L<threads> methods in such an C<END> block will most
1078 mutexes that are needed to control functionality within the L<threads> module.
1080 For this reason, the use of C<END> blocks in threads is B<strongly>
1088 threads. You can use the C<d_fchdir> variable in L<Config.pm|Config> to
1091 In prior perl versions, spawning threads with open directory handles would
1095 =item Detached threads and global destruction
1097 If the main thread exits while there are detached threads which are still
1099 otherwise certain global structures that control the operation of threads and
1105 detached threads, but rather join all threads before exiting the program.
1107 =item Perl Bugs and the CPAN Version of L<threads>
1109 Support for threads extends beyond the code in this module (i.e.,
1110 F<threads.pm> and F<threads.xs>), and into the Perl interpreter itself. Older
1112 latest version of L<threads> from CPAN. There is no workaround for this other
1116 with threads may result in warning messages concerning leaked scalars or
1120 You can search for L<threads> related bug reports at
1122 patches, etc. to: L<https://rt.cpan.org/Public/Dist/Display.html?Name=threads>
1132 threads on MetaCPAN:
1133 L<https://metacpan.org/release/threads>
1136 L<https://github.com/Dual-Life/threads>
1138 L<threads::shared>, L<perlthrtut>
1140 L<https://www.perl.com/pub/a/2002/06/11/threads.html> and
1141 L<https://www.perl.com/pub/a/2002/09/04/threads.html>
1143 Perl threads mailing list:
1159 threads is released under the same license as Perl.