Where Wizards Fear To Tread

Jun 11, 2002 by Artur Bergman

One of the big new features in perl 5.8 is that we now have real working threads available to us through the threads pragma.

However, for us module authors who already have to support our modules on different versions of perl and different platforms, we now have to deal with another case: threads! This article will show you how threads relate to modules, how we can take old modules and make them thread-safe, and round off with a new module that alters perl’s behavior of the “current working directory”.

To run the examples I have shown here, you need perl 5.8 RC1 or later compiled with threads. On Unix, you can use Configure -Duseithreads -Dusethreads; On Win32, the default build will always have threading enabled.

How do threads relate to modules?

Threading in Perl is based on the notion of explicit shared data. That is, only data that is explicitly requested to be shared will be shared between threads. This is controlled by the threads::shared pragma and the “: shared” attribute. Witness how it works:

     use threads;
     my $var = 1;
     threads->create(sub { $var++ })->join();
     print $var;

If you are accustomed to threading in most other languages, (Java/C) you would expect $var to contain a 2 and the result of this script to be “2”. However since Perl does not share data between threads, $var is copied in the thread and only incremented in the thread. The original value in the main thread is not changed, so the output is “1”.

However if we add in threads::shared and a : shared attribute we get the desired result:

     use threads;
     use threads::shared;
     my $var : shared = 1;
     threads->create(sub { $var++ })->join();
     print $var

Now the result will be “2”, since we declared $var to be a shared variable. Perl will then act on the same variable and provide automatic locking to keep the variable out of trouble.

This makes it quite a bit simpler for us module developers to make sure our modules are thread-safe. Essentially, all pure Perl modules are thread-safe because any global state data, which is usually what gives you thread-safety problems, is by default local to each thread.

Definition of thread-safe levels

To define what we mean by thread-safety, here are some terms adapted from the Solaris thread-safety levels.

thread-safe

This module can safely be used from multiple threads. The effect of calling into a safe module is that the results are valid even when called by multiple threads. However, thread-safe modules can still have global consequences; for example, sending or reading data from a socket affects all threads that are working with that socket. The application has the responsibility to act sane with regards to threads. If one thread creates a file with the name file.tmp then another file which tries to create it will fail; this is not the fault of the module.

thread-friendly

Thread-friendly modules are thread-safe modules that know about and provide special functions for working with threads or utilize threads by themselves. A typical example of this is the core threads::queue module. One could also imagine a thread-friendly module with a cache to declare that cache to be shared between threads to make hits more likely and save memory.

thread-unsafe

This module can not safely be used from different threads; it is up to the application to synchronize access to the library and make sure it works with it the way it is specified. Typical examples here are XS modules that utilize external unsafe libraries that might only allow one thread to execute them.

Since Perl only shares when asked to, most pure Perl code probably falls into the thread-safe category, that doesn’t mean you should trust it until you have review the source code or they have been marked with thread-safe by the author. Typical problems include using alarm(), mucking around with signals, working with relative paths and depending on %ENV. However remember that ALL XS modules that don’t state anything fall into the definitive thread-unsafe category.

Why should I bother making my module thread-safe or thread-friendly?

Well, it usually isn’t much work and it will make the users of this modules that want to use it in a threaded environment very happy. What? Threaded Perl environments aren’t that common you say? Wait until Apache 2.0 and mod_perl 2.0 becomes available. One big change is that Apache 2.0 can run in threaded mode and then mod_perl will have to be run in threaded mode; this can be a huge performance gain on some operating systems. So if you want your modules to work with mod_perl 2.0, taking a look at thread-safety levels is a good thing to do.

So what do I do to make my module thread-friendly?

A good example of a module that needed a little modification to work with threads is Michael Schwern’s most excellent Test::Simple suite (Test::Simple, Test::More and Test::Builder). Surprisingly, we had to change very little to fix it.

The problem was simply that the test numbering was not shared between threads.

For example

     use threads;
     use Test::Simple tests => 3;
     ok(1);
     threads->create(sub { ok(1) })->join();
     ok(1);

Now that will return

     1..3
     ok 1
     ok 2
     ok 2

Does it look similar to the problem we had earlier? Indeed it does, seems like somewhere there is a variable that needs to shared.

Now reading the documentation of Test::Simple we find out that all magic is really done inside Test::Builder, opening up Builder.pm we quickly find the following lines of code:

     my @Test_Results = ();
     my @Test_Details = ();
     my $Curr_Test = 0;

Now we would be tempted to add use threads::shared and :shared attribute.

     use threads::shared;
     my @Test_Results : shared = ();
     my @Test_Details : shared = ();
     my $Curr_Test : shared = 0;

However Test::Builder needs to work back to Perl 5.4.4! Attributes were only added in 5.6.0 and the above code would be a syntax error in earlier Perls. And even if someone were using 5.6.0, threads::shared would not be available for them.

The solution is to use the runtime function share() exported by threads::shared, but we only want to do it for 5.8.0 and when threads have been enabled. So, let’s wrap it in a BEGIN block and an if.

     BEGIN{
         if($] >= 5.008 && exists($INC{'threads.pm'})) {
             require threads::shared;
             import threads::shared qw(share);
             share($Curr_Test);
             share(@Test_Details)
             share(@Test_Results);
         }

So, if 5.8.0 or higher and threads has been loaded, we do the runtime equivalent of use threads::shared qw(share); and call share() on the variables we want to be shared.

Now lets find out some examples of where $Curr_Test is used. We find sub ok {} in Test::Builder; I won’t include it here, but only a smaller version which contains:

     sub ok {
         my($self, $test, $name) = @_;
         $Curr_Test++;
         $Test_Results[$Curr_Test-1] = 1 unless($test);
     }

Now, this looks like it should work right? We have shared $Curr_Test and @Test_Results. Of course, things aren’t that easy; they never are. Even if the variables are shared, two threads could enter ok() at the same time. Remember that not even the statement $CurrTest++ is an atomic operation, it is just a shortcut for writing $CurrTest = $CurrTest + 1. So let’s say two threads do that at the same time.

     Thread 1: add 1 + $Curr_Test
     Thread 2: add 1 + $Curr_Test
     Thread 2: Assign result to $Curr_Test
     Thread 1: Assign result to $Curr_Test

The effect would be that $Curr_Test would only be increased by one, not two! Remember that a switch between two threads could happen at ANY time, and if you are on a multiple CPU machine they can run at exactly the same time! Never trust thread inertia.

So how do we solve it? We use the lock() keyword. lock() takes a shared variable and locks it for the rest of the scope, but it is only an advisory lock so we need to find every place that $Curr_Test is used and modified and it is expected not to change. The ok() becomes:

     sub ok {
         my($self, $test, $name) = @_;
         lock($Curr_Test);
         $Curr_Test++;
         $Test_Results[$Curr_Test-1] = 1 unless($test);
     }

So are we ready? Well, lock() was only added in Perl 5.5 so we need to add an else to the BEGIN clause to define a lock function if we aren’t running with threads. The end result would be.

     my @Test_Results = ();
     my @Test_Details = ();
     my $Curr_Test = 0;
     BEGIN{
         if($] >= 5.008 && exists($INC{'threads.pm'})) {
             require threads::shared;
             import threads::shared qw(share);
             share($Curr_Test);
             share(@Test_Details)
             share(@Test_Results);
         } else {
             *lock = sub(*) {};
         }
     }
     sub ok {
         my($self, $test, $name) = @_;
         lock($Curr_Test);
         $Curr_Test++;
         $Test_Results[$Curr_Test-1] = 1 unless($test);
     }

In fact, this is very like the code that has been added to Test::Builder to make it work nice with threads. The only thing not correct is ok() as I cut it down to what was relevant. There were roughly 5 places where lock() had to be added. Now the test code would print

     1..3
     ok 1
     ok 2
     ok 3

which is exactly what the end user would expect. All in all this is a rather small change for this 1291 line module, we change roughly 15 lines in a non intrusive way, the documentation and testcase code makes up most of the patch. The full patch is at http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2002-06/msg00816.html

Altering Perls behavior to be thread-safe, ex::threads::cwd

Somethings change when you use threads; some things that you or a module might do are not like what they used to be. Most of the changes will be due to the way your operating system treats processes that use threads. Each process has typically a set of attributes, which include the current working directory, the environment table, the signal subsystem and the pid. Since threads are multiple paths of execution inside a single process, the operating system treats it as a single process and you have a single set of these attributes.

Yep. That’s right - if you change the current working directory in one thread, it will also change in all the other threads! Whoops, better start using absolute paths everywhere, and all the code that uses your module might use relative paths. Aaargh…

Don’t worry, this is a solvable problem. In fact, it’s solvable by a module.

Perl allows us to override functions using the CORE::GLOBAL namespace. This will let us override the functions that deal with paths and set the cwd correctly before issuing the command. So let’s start off

     package ex::threads::safecwd;

     use 5.008;
     use strict;
     use warnings;
     use threads::shared;
     our $VERSION = '0.01';

Nothing weird here right? Now, when changing and dealing with the current working directory one often uses the Cwd module, so let us make the cwd module safe first. How do we do that?

  1) use Cwd;
  2) our $cwd = cwd;  #our per thread cwd, init on startup from cwd
  3) our $cwd_mutex : shared; # the variable we use to sync
  4) our $Cwd_cwd = \&Cwd::cwd;
  5) *Cwd::cwd = *my_cwd;     
     sub my_cwd {
  6)     lock($cwd_mutex);
  7)     CORE::chdir($cwd);
  8)     $Cwd_cwd->(@_);
     }

What’s going on here? Let’s analyze it line by line:

We include Cwd.
We declare a variable and assign to it the cwd we start in. This variable will not be shared between threads and will contain the cwd of this thread.
We declare a variable we will be using to lock for synchronizing work.
Here we take a reference to the &Cwd::cwd and store in $Cwd_cwd.
Now we hijack Cwd::cwd and assign to it our own my_cwd so whenever someone calls Cwd::cwd, it will call my_cwd instead.
my_cwd starts of by locking $cwd_mutex so no one else will muck. around with the cwd.
After that we call CORE::chdir() to actually set the cwd to what this thread is expecting it to be.
And we round off by calling the original Cwd::cwd that we stored in step 4 with any parameters that we were handed to us.

In effect we have hijacked Cwd::cwd and wrapped it around with a lock and a chdir so it will report the correct thing!

Now that cwd() is fixed, we need a way to actually change the directory. To do this, we install our own global chdir, simply like this.

     *CORE::GLOBAL::chdir = sub {
         lock($cwd_mutex);
         CORE::chdir($_[0]) || return undef;
         $cwd = $Cwd_cwd->();
     };

Now, whenever someone calls chdir() our chdir will be called instead, and in it we start by locking the variable controlling access, then we try to chdir to the directory to see if it is possible, otherwise we do what the real chdir would do, return undef. If it succeeds, we assign the new value to our per thread $cwd by calling the original Cwd::cwd()

The above code is actually enough to allow the following to work:

     use threads
     use ex::threads::safecwd;
     use Cwd;
     chdir("/tmp");
     threads->create(sub { chdir("/usr") } )->join();
     print cwd() eq '/tmp' ? "ok" : "nok";

Since the chdir("/usr"); inside the thread will not affect the other thread’s $cwd variable, so when cwd is called, we will lock down the thread, chdir() to the location the thread $cwd contains and perform a cwd().

While this is useful, we need to get along and provide some more functions to extend the functionality of this module.

     *CORE::GLOBAL::mkdir = sub {
         lock($cwd_mutex);
         CORE::chdir($cwd);
         if(@_ > 1) {
             CORE::mkdir($_[0], $_[1]);
         } else {
             CORE::mkdir($_[0]);
         }
     };

     *CORE::GLOBAL::rmdir = sub {
         lock($cwd_mutex);
         CORE::chdir($cwd);
         CORE::rmdir($_[0]);
     };

The above snippet does essentially the same thing for both mkdir and rmdir. We lock the $cwd_mutex to synchronize access, then we chdir to $cwd and finally perform the action. Worth noticing here is the check we need to do for mkdir to be sure the prototype behavior for it is correct.

Let’s move on with opendir, open, readlink, readpipe, require, rmdir, stat, symlink, system and unlink. None of these are really any different from the above with the big exception of open. open has a weird bit of special case since it can take both a HANDLE and an empty scalar for autovification of an anonymous handle.

     *CORE::GLOBAL::open = sub (*;$@) {
         lock($cwd_mutex);
         CORE::chdir($cwd);
         if(defined($_[0])) {
             use Symbol qw();
             my $handle = Symbol::qualify($_[0],(caller)[0]);
             no strict 'refs';
             if(@_ == 1) {
                 return CORE::open($handle);
             } elsif(@_ == 2) {
               return CORE::open($handle, $_[1]);
             } else {
               return CORE::open($handle, $_[1], @_[2..$#_]);
             }
         }

Starting off with the usual lock and chdir() we then need to check if the first value is defined. If it is, we have to qualify it to the callers namespace. This is what would happen if a user does open FOO, "+>foo.txt". If the user instead does open main::FOO, "+>foo.txt", then Symbol::qualify notices that the handle is already qualified and returns it unmodified. Now since $_[0] is a readonly alias we cannot assign it over so we need to create a temporary variable and then proceed as usual.

Now if the user used the new style open my $foo, "+>foo.txt", we need to treat it differently. The following code will do the trick and complete the function.

     else {
             if(@_ == 1) {
                 return CORE::open($_[0]);
             } elsif(@_ == 2) {
                 return CORE::open($_[0], $_[1]);
             } else {
                 return CORE::open($_[0], $_[1], @_[2..$#_]);
             }
         }
     };

Wonder why we couldn’t just assign $_[0] to $handle and unify the code path? You see, $_[0] is an alias to the $foo in open my $foo, "+>foo.txt" so CORE::open will correctly work.

However, if we do $handle = $_[0] we take a copy of the undefined variable and CORE::open won’t do what I mean.

So now we have a module that allows the you to safely use relative paths in most of the cases and vastly improves your ability to port code to a threaded environment. The price we pay for this is speed, since every time you do an operation involving a directory you are serializing your program. Typically, you never do those kinds of operations in a hot path anyway. You might do work on your file in a hot path, but as soon as we have gotten the filehandle no more locking is done.

A couple of problems remain. Performance-wise, there is one big problem with system(), since we don’t get control back until the CORE::system() returns, so all path operations will hang waiting for that. To solve that we would need to revert to XS and do some magic with regard to the system call. We also haven’t been able to override the file test operators (-x and friends), nor can we do anything about qx {}. Solving that problem requires working up and down the optree using B::Generate and B::Utils. Perhaps a future version of the module will attempt that together with a custom op to do the locking.

Conclusion

Threads in Perl are simple and straight forward, as long as we stay in pure Perl land everything behaves just about how we would expect it to. Converting your modules should be a simple matter of programming without any big wizardly things to be done. The important thing to remember is to think about how your module could possibly take advantage of threads to make it easier to use for the programmer.

Moving over to XS land is altogether different; stay put for the next article that will take us through the pitfalls of converting various kinds of XS modules to thread-safe and thread-friendly levels.

Tags

development