From: Jarkko Hietaniemi Date: Thu, 18 Jul 2002 17:50:27 +0000 (+0000) Subject: Thread-safety doc tweaks from Jörg Walter ; X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cf5baa4869b9f9ab8e2d559f474c8e805806c370;p=p5sagit%2Fp5-mst-13.2.git Thread-safety doc tweaks from Jörg Walter ; add a note about process-scope changing functions to perlthrtut as suggested by Stas Bekman. p4raw-id: //depot/perl@17625 --- diff --git a/pod/perlthrtut.pod b/pod/perlthrtut.pod index dbc792d..25a4edf 100644 --- a/pod/perlthrtut.pod +++ b/pod/perlthrtut.pod @@ -202,14 +202,15 @@ system blocks the entire process on sleep(), Perl usually will as well. Perl Threads Are Different. -=head1 Threadsafe Modules +=head1 Thread-Safe Modules -The addition of threads has changed Perl's internals +The addition of threads has changed Perl's internals substantially. There are implications for people who write -modules with XS code or external libraries. However, since the threads -do not share data, pure Perl modules that don't interact with external -systems should be safe. Modules that are not tagged as thread-safe should -be tested or code reviewed before being used in production code. +modules with XS code or external libraries. However, since perl data is +not shared among threads by default, Perl modules stand a high chance of +being thread-safe or can be made thread-safe easily. Modules that are not +tagged as thread-safe should be tested or code reviewed before being used +in production code. Not all modules that you might use are thread-safe, and you should always assume a module is unsafe unless the documentation says @@ -217,17 +218,18 @@ otherwise. This includes modules that are distributed as part of the core. Threads are a new feature, and even some of the standard modules aren't thread-safe. -Even if a module is threadsafe, it doesn't mean that the module is optimized +Even if a module is thread-safe, it doesn't mean that the module is optimized to work well with threads. A module could possibly be rewritten to utilize the new features in threaded Perl to increase performance in a threaded environment. If you're using a module that's not thread-safe for some reason, you -can protect yourself by using semaphores and lots of programming -discipline to control access to the module. Semaphores are covered -later in the article. +can protect yourself by using it from one, and only one thread at all. +If you need multiple threads to access such a module, you can use semaphores and +lots of programming discipline to control access to it. Semaphores +are covered in L. -See also L. +See also L. =head1 Thread Basics @@ -253,19 +255,19 @@ like: A possibly-threaded program using a possibly-threaded module might have code like this: - use Config; - use MyMod; + use Config; + use MyMod; BEGIN { - if ($Config{useithreads}) { - # We have threads - require MyMod_threaded; - import MyMod_threaded; - } else { - require MyMod_unthreaded; - import MyMod_unthreaded; + if ($Config{useithreads}) { + # We have threads + require MyMod_threaded; + import MyMod_threaded; + } else { + require MyMod_unthreaded; + import MyMod_unthreaded; } - } + } Since code that runs both with and without threads is usually pretty messy, it's best to isolate the thread-specific code in its own @@ -404,7 +406,7 @@ automatically. $thr->detach; # Now we officially don't care any more - sub sub1 { + sub sub1 { $a = 0; while (1) { $a++; @@ -974,20 +976,42 @@ be little different than ordinary code. Also note that under the current implementation, shared variables use a little more memory and are a little slower than ordinary variables. -=head1 Threadsafety of System Libraries +=head1 Process-scope Changes + +Note that while threads themselves are separate execution threads and +Perl data is thread-private unless explicitly shared, the threads can +affect process-scope state, affecting all the threads. + +The most common example of this is changing the current working +directory using chdir(). One thread calls chdir(), and the working +directory of all the threads changes. -Whether various library calls are threadsafe is outside the control -of Perl. Calls often suffering from not being threadsafe include: +Even more drastic example of a process-scope change is chroot(): +the root directory of all the threads changes, and no thread can +undo it (as opposed to chdir()). + +Further examples of process-scope changes include umask() and +changing uids/gids. + +Thinking of mixing fork() and threads? Please lie down and wait +until the feeling passes-- but in case you really want to know, +the semantics is that fork() duplicates all the threads. +(In UNIX, at least, other platforms will do something different.) + +=head1 Thread-Safety of System Libraries + +Whether various library calls are thread-safe is outside the control +of Perl. Calls often suffering from not being thread-safe include: localtime(), gmtime(), get{gr,host,net,proto,serv,pw}*(), readdir(), -rand(), and srand() -- in general, calls that depend on some external -state. +rand(), and srand() -- in general, calls that depend on some global +external state. -If the system Perl is compiled in has threadsafe variants of such +If the system Perl is compiled in has thread-safe variants of such calls, they will be used. Beyond that, Perl is at the mercy of -the threadsafety or unsafety of the calls. Please consult your +the thread-safety or -unsafety of the calls. Please consult your C library call documentation. -In some platforms the threadsafe interfaces may fail if the result +In some platforms the thread-safe interfaces may fail if the result buffer is too small (for example getgrent() may return quite large group member lists). Perl will retry growing the result buffer a few times, but only up to 64k (for safety reasons). @@ -1065,6 +1089,9 @@ Dan Sugalski Edan@sidhe.org Slightly modified by Arthur Bergman to fit the new thread model/module. +Reworked slightly by Jörg Walter Ejwalt@cpan.org to be more concise +about thread-safety of perl code. + =head1 Copyrights The original version of this article originally appeared in The Perl