This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Thread Programming Model
=head1 VERSION
Maintainer: Steven McDougall <[EMAIL PROTECTED]>
Date: 31 Aug 2000
Last Modified: 26 Sep 2000
Mailing List: [EMAIL PROTECTED]
Number: 185
Version: 3
Status: Frozen
=head1 ABSTRACT
This RFC describes the programming interface to Perl6 threads.
It documents the function calls, operators, classes, methods, or
whatever else the language provides for programming with threads.
=head1 CHANGES
=head2 v3
Frozen
=head2 v2
=over 4
=item *
Added SYNOPSIS, and wrote a proper ABSTRACT
=item *
Detailed C<async>
=item *
Detailed sharing of lexicals between threads
=item *
Traded Mutexes back for C<lock>, C<try>, and C<unlock>
=item *
Pushed C<Semaphore>, C<Event>, and C<Timer> down into C<Thread::>
=item *
Specified readable, writable and failure to return Events
=item *
Reworked the wait functions
=item *
Added C<Queue>
=back
=head1 FREEZE
There was little, if any, further discussion after version 2.
=head1 SYNOPSIS
use Thread;
$sub = sub { ... };
$thread = new Thread \&func , @args;
$thread = new Thread $sub , @args;
$thread = new Thread sub { ... }, @args;
async { ... };
$result = join $thread;
$thread = this Thread;
@threads = all Thread;
$thread1 == $thread2 and ...
Thread::yield();
critical { ... }; # one thread at a time in this block
lock $scalar;
lock @array
lock %hash;
lock ⊂
$ok = try $scalar;
$ok = try @array
$ok = try %hash;
$ok = try ⊂
unlock $scalar;
unlock @array
unlock %hash;
unlock ⊂
$event = auto Thread::Event;
$event = manual Thread::Event;
set $event;
reset $event;
wait $event;
$semaphore = new Thread::Semaphore $initial;
$ok = $semaphore->up($n);
$semaphore->down;
$count = $semaphore->count;
$timer = Thread::Timer->delay($seconds);
$timer = Thread::Timer->alarm($time);
$timer->wait;
$event = $fh->readable
$event = $fh->writable
$event = $fh->failure
$ok = wait_all(@references);
$i = wait_any(@references);
$queue = new Thread::Queue
$queue->enqueue($a);
$a = $queue->dequeue;
$empty = $queue->empty;
=head1 DESCRIPTION
=head2 Thread
=over 4
=item I<$thread> = C<new> C<Thread> \&I<func>, I<@args>
Executes I<func>(I<@args>) in a separate thread. The return value is
a reference to the C<Thread> object that manages the thread.
The subroutine executes in its enclosing lexical context. This means
that lexical variables declared in that context may be shared between
threads. See RFC 178 for examples.
=item I<$thread> = C<new> C<Thread> I<$sub>, I<@args>
=item I<$thread> = C<new> C<Thread> C<sub> { ... }, I<@args>
Executes an anonymous subroutine in a separate thread, passing it
I<@args>. The return value is a reference to the C<Thread> object that
manages the thread.
The subroutine is a closure. References to variables in its lexical
context are bound when the C<sub> operator executes. See RFC 178 for
examples.
=item C<async> BLOCK
Executes BLOCK in a separate thread. Syntactically, C<async> BLOCK
works like C<do> BLOCK. C<async> creates a C<Thread> object to manage
the thread, but it does not return a reference to it. If you want the
C<Thread> object, use one of the C<new> C<Thread> forms shown above.
The BLOCK executes in its enclosing lexical context. This means that
lexical variables declared in that context may be shared between
threads.
=item I<$thread> = C<this> C<Thread>
Returns a reference to the C<Thread> object that manages the current
thread.
=item I<@threads> = C<all> C<Thread>
Returns a list of references to all existing C<Thread> objects in the
program. This includes C<Thread> objects created for C<async> blocks.
=item I<$result> = C<join> I<$thread>
=item I<@result> = C<join> I<$thread>
Blocks until I<$thread> terminates. May be called repeatedly,
by any number of threads.
Returns the last expression evaluated in I<$thread>. This expression
is evaluated in list context inside the thread.
If C<join> is called in list context, it returns the entire list; if
C<join> is called in scalar context, it returns the first element of
the list.
=item I<$thread1> == I<$thread2>
Evaluates to true iff I<$thread1> and I<$thread2> reference the same
C<Thread> object.
=item C<Thread::yield>()
Gives the interpreter an opportunity to switch to another thread. The
interpreter is not obligated to take this opportunity, and the calling
thread may regain control after an arbitrarily short period of time.
=back
=head2 Critical section
C<critical> is a new keyword. Syntactically, it works like C<do>.
critical { ... };
The interpreter guarantees that only one thread at a time can execute
a C<critical> block.
=head2 Lock
=over 4
=item C<lock> I<$scalar>
=item C<lock> I<@array>
=item C<lock> I<%hash>
=item C<lock> I<&sub>
Applies a lock to a variable.
If there are no locks applied to the variable, applies a lock and
returns immediately.
If there are locks applied by another thread, blocks until there are
no locks applied.
If there are locks applied by the calling thread, applies another lock
and returns immediately.
The lock is automatically removed at the end of the lexical scope in
which the C<lock> operator executes.
=item I<$ok> = C<try> I<$scalar>
=item I<$ok> = C<try> I<@array>
=item I<$ok> = C<try> I<%hash>
=item I<$ok> = C<try> I<&sub>
Tries to apply a lock to a variable.
If there are no locks applied to the variable, applies a lock and
returns true.
If there are locks applied by another thread, returns false.
If there are locks applied by the calling thread, applies another lock
and returns true.
The lock is automatically removed at the end of the lexical scope in
which the C<lock> operator executes.
C<try> never blocks.
=item C<unlock> I<$scalar>
=item C<unlock> I<@array>
=item C<unlock> I<%hash>
=item C<unlock> I<&sub>
Removes a lock from a variable.
If there are locks applied by the calling thread, removes one.
If there are locks applied by another thread, does nothing.
If there are no locks applied to the variable, does nothing.
C<unlock> never blocks.
=back
A consequence of these rules is that only one thread at a time may have
locks applied to a variable.
=head2 Event
Events allow one thread to wait until something happens in another
thread.
Events have two states: I<set> and I<reset>. Threads I<wait> on an
event; the C<wait> call blocks until the event is set.
There are two kinds of events: I<manual> and I<automatic>.
When a manual event is set, it remains set until a C<reset> call
is made on it. All waiting threads are immediately unblocked, and
subsequent calls to C<wait> return immediately.
When an automatic event is set, one waiting thread is unblocked and
the event is immediately reset. If there are no waiting threads, the
first call to C<wait> resets the event and returns immediately.
=over 4
=item I<$event> = C<auto> C<Thread::Event>
Creates and returns an automatic C<Event> object. The event is initially reset.
=item I<$event> = C<manual> C<Thread::Event>
Creates and returns a manual C<Event> object. The event is initially reset.
=item C<set> I<$event>
Sets I<$event>.
When a manual event is set, it remains set until a C<reset> call is
made on it. During this time, any number of threads may C<wait> on it
without blocking. When an automatic event is set, it is reset by the
first thread that C<wait>s on it.
=item C<reset> I<$event>
Resets I<$event>.
=item C<wait> I<$event>
Blocks until I<$event> is set.
=back
=head2 Semaphore
A semaphore manages a number, called a I<count>. The count is always
between zero and a system-dependent maximum. C<up> and C<down> are
guaranteed to execute atomically.
=over 4
=item I<$semaphore> = C<new> C<Thread::Semaphore> I<$n>
Creates and returns a new C<Semaphore> object, with an initial count
of I<$n>. If I<$n> is omitted, the initial count is zero.
=item I<$ok> = C<$semaphore>->C<up>(I<$n>)
If the count can be increased by I<$n> without exceeding the maximum,
does so and returns true. Otherwise, does nothing and returns false.
If I<$n> is omitted, it defaults to 1.
=item I<$semaphore>->C<down>
Blocks until the count is positive, then decrements the count and
returns.
=item I<$count> = I<$semaphore>->C<count>
Returns the current count of I<$semaphore>.
C<count> is typically used at program termination to release all the
resources controlled by a semaphore.
Code that uses C<count> while more than one thread has access to
I<$semaphore> is subject to race conditions.
=back
=head2 Timer
=over 4
=item I<$timer> = C<Thread::Timer>->C<delay>(I<$seconds>)
Creates and returns a new C<Timer> object. The timer will expire
I<$seconds> seconds after it is created. I<$seconds> may be a floating
point number, so this interface supports whatever time resolution the
platform provides.
=item I<$timer> = C<Thread::Timer>->C<alarm>(I<$time>)
Creates and returns a new C<Timer> object. The timer will expire at
I<$time> seconds after the epoch. I<$time> may be floating point
number, so this interface supports whatever time resolution the
platform provides.
=item C<wait> I<$timer>
Blocks until the timer expires.
=back
=head2 I/O
=over 4
=item I<$event> = I<$fh>->C<readable>
Returns a reference to a C<Thread::Event> object that is set when a
read on the file handle will not block.
=item I<$event> = I<$fh>->C<writable>
Returns a reference to a C<Thread::Event> object that is set when a
write on the file handle will not block.
=item I<$event> = I<$fh>->C<readable>
Returns a reference to a C<Thread::Event> object that is set when I/O
on the file handle will fail.
=back
=head2 Wait functions
Threads, variables, events, semaphores, and timers are
I<synchronization objects>. A synchronization object is I<signaled>
when a thread would not block on it. The conditions for an object to
be signaled depend on the kind of object.
=over 4
=item *
Threads are signaled after they have completed execution.
=item *
Variables are signaled while there are no locks applied to them.
=item *
Events are signaled while they are set.
=item *
Semaphores are signaled while they have a positive count.
=item *
Timers are signaled after they expire.
=back
=over 4
=item I<$ok> = C<Thread::wait_all>(I<@references>)
C<wait_all> takes a list of references to synchronization objects.
It blocks until all of the objects are signaled.
C<wait_all> changes the state of the objects as follows
=over 4
=item *
it applies a lock to variables
=item *
it resets automatic events
=item *
it decrements the count of semaphores
=item *
it does not change the state of other kinds of synchronization objects
=back
C<wait_all> does not change the state of any object until all the
objects are signaled. This prevents deadlock, at least between
competing wait functions.
Returns true on success, false on error. An error occurs if an element
of I<@references> is not a reference.
=item I<$i> = C<Thread::wait_any>(I<@references>)
C<wait_any> takes a list of references to synchronization objects. It
blocks until at least one of the objects is signaled.
On success, returns the index in I<@references> of one of the objects
that was signaled. The state of this object may be changed, as
described above for C<wait_all>.
Returns -1 on error. An error occurs if an element of I<@references>
is not a reference.
=back
=head2 Queue
C<Thread::Queue> implements a thread-safe queue of scalars.
=over 4
=item I<$queue> = C<new> C<Thread::Queue>
Creates and returns a new C<Thread::Queue> object.
The queue is initially empty.
=item I<$queue>->C<enqueue>(I<$a>)
Places I<$a> at the tail of the queue.
=item I<$a> = I<$queue>->C<dequeue>
Blocks while I<$queue> is empty.
Then removes and returns the scalar at the head of the queue.
=item I<$empty> = I<$queue>->C<empty>
Returns true iff the queue is currently empty.
C<empty> is typically used at program termination to remove all
elements from a queue.
Code that uses C<empty> while more than one thread has access to
I<$queue> is subject to race conditions.
=back
=head1 IMPLEMENTATION
All of these features should be doable if threads are built into Perl.
Implementing the C<readable>, C<writable> and C<failure> methods on
file handles probably requires asynchronous I/O.
Not everything has to be in the core. For example, Semaphores can be
built from Events, and Queues can be built from Semaphores.
=head1 DISCUSSION
This interface is an amalgam of
=over 4
=item *
the C<Thread.pm> interface from Perl 5.6.0
=item *
the Win32 thread interface
=item *
my own wish list (you can't get it if you don't ask...)
=back
Here are some issues to consider
=head2 Thread creation
Threads are created by
new Thread \&func
new Thread sub { ... }
async { ... }
We arguably don't need three different ways to create threads.
However, the different syntaxes fit into the language in slightly
different ways, and I'm not sure which one I'd be willing to give up.
The first is the most fundamental; losing it would be a serious
inconvenience. Perl generally allows an anonymous subroutine where
ever it allows a code ref, so the second also seems appropriate. And
the third allows us to create threads with the kind of lightweight
syntax that makes Perl such a lucid language.
=head2 C<join>
The calling context of C<join> can't be propagated into the thread,
for several reasons.
=over 4
=item *
The thread can compute only one return value, but C<join> can be
called repeatedly in different contexts.
=item *
The thread might terminate before the first call to join. C<join> can
return the last expression evaluated in the thread, but it can't
retroactively affect the context in which that expression was evaluated.
=back
Not allowing multiple C<join>s on a thread might help with the first
problem; I can't see any way around the second.
=head2 Critical sections
This interface provides the
critical { ... }
construct. In principle, we don't need this: you can do the same thing
with scoped locks
sub foo
{
lock &foo;
...
}
sub bar
{
{
lock $bar::a;
...
}
{
lock $bar::b;
...
}
}
Nonetheless, critical sections have several attractive features.
=over 4
=item *
They reduce clutter. No named variable to lock.
=item *
Along with less clutter comes fewer chances for bugs. There isn't a
locked variable floating around to get locked by the wrong thread, or
locked and never unlocked, or deadlocked, or...
=item *
The implementation can be highly optimized. Internally, a critical
section is protected by some kind of mutex. However, this mutex isn't
user visible: the interpreter has complete control over it. Therefore,
it can be very lightweight.
=back
Efficiency matters, because critical sections are used to manage things that
are...well...critical. Important, global, high-contention resources like
memory managers and process schedulers. Granted, these are poor
examples for Perl, but you get the idea.
Whether to implement C<critical> depends partly on whether serializing
execution of a block of code is common enough to merit its own keyword
and syntax. Threads.pm in Perl 5.6.0 documents a C<:locked> attribute
for subroutines; given a choice, I'd rather have C<critical> than
C<:locked>.
=head2 Locked variables
Following some discussion on perl6-language-flow, I traded mutexes
back for locked variables. This led to some changes in the wait functions.
=head2 Events
I dropped the C<cond_xxx> mechanism in C<Threads.pm> in favor of
Events. Events do essentially the same thing with a simpler interface.
In particular, Events don't expose a locked variable the way
C<cond_xxx> does. (As far as I can tell, this variable is an artifact
of the PThreads implementation.)
One substantive difference between Events and C<cond_xxx> is that the
manual/automatic distinction for Events is a property of the Event
object, while the corresponding broadcast/signal distinction for
C<cond_xxx> is a property of the signaling call. It isn't clear to me
whether one model is preferable to the other.
Another difference is that C<set> and C<reset> I<change the state> of
an Event object, while C<cond_signal> and C<cond_broadcast> I<send a
signal> to threads that are blocked on C<cond_wait>. This reminds me
of the level sensitive/edge sensitive distinction for hardware
interrupts. Having seen the grief caused by edge sensitive interrupts
in the original IBM PC, I am leery of things that resemble them.
Perhaps someone can make a case that this is a false analogy.
Following some discussion on perl6-language-flow, I reviewed the
documentation for the C<cond_xxx> functions in Perl 5.6.0. It begins
The C<cond_wait> function takes a B<locked> variable as a
parameter, unlocks the variable,
However, C<Thread/Semaphore.pm> in the same release uses the
C<cond_xxx> functions I<without> locking the condition variable. All I
can say at this point is that I do not understand the C<cond_xxx>
functions. Perhaps someone can submit an RFC documenting them and
showing how to use them.
=head2 C<die>
I dropped the I<$thread>->C<eval> call from this interface, and didn't
say what happens if a thread C<die>s. There are several possibilities
=over 4
=item *
The exception is propagated to any thread that C<join>s it. This has a
certain logic to it, but it suffers from the fact that a program
needn't C<join> its threads, so it doesn't guarantee that exceptions
will actually be handled.
=item *
The interpreter prints C<$@> on stderr and exits. This is what C++
does. It ensures that exceptions won't just disappear into the void;
however, it also causes a good deal of anxiety and paranoia, because
I<any> thread can potentially blow your program out of the water. (I
speak from experience here.)
=item *
The thread just quietly goes away. After working with threads in C++,
I'm actually partial to this one. We still need some way to recover
C<$@> when a thread C<die>s. Returning C<$@> to C<join> is probably
the Wrong Thing.
=back
=head2 C<==>
I dropped I<$thread>->C<equal> in favor of overloading C<==> to
compare threads. This seems more natural, and should be easy to
implement if threads are built into the language.
=head2 Thread IDs
I dropped thread IDs from the interface. You don't want thread IDs.
Thread IDs are an implementation artifact. Carrying around explicit
numerical indices isn't the Perl way. They were broken anyway (wrap at
2^32, with no guarantee of uniqueness after that).
=head2 Detach
I dropped C<detach> from the interface. Detach is an artifact of
languages that require programmers to manage their own storage. It has
rigorous semantics, there's no going back, and if you get it wrong,
you either leak threads or you crash.
In Perl, detachment is more a state of mind. We have threads, and we
have C<Thread> objects to manage them. The thread holds a reference on
its C<Thread> object until it terminates. The C<Thread> object holds a
reference on its thread as long as the C<Thread> object exists.
If there are no user-visible references to a C<Thread> object (i.e.
the only reference on the C<Thread> object is the one held by the
thread), then the thread is said to be detached. A call to
C<Thread>->C<all> or C<Thread>->C<this> could recover a reference to
the C<Thread> object of a detached thread; when this happens, the
thread is no longer detached.
In any case, you don't have to worry about it. Like so many others,
C<detach> is a problem that Perl doesn't have.
=head2 Import
To minimize namespace pollution, we could @EXPORT_OK the functions
that appear in this interface.
use Threads qw(yield wait_all wait_any)
On the other hand, if they get moved into the core the issue may be
moot.
=head2 I/O
C<readable>, C<writable>, and C<failure> are documented as being
file handle methods; however, it is anticipated that file handles will
subsume sockets in Perl6. For an unconnected socket, the semantics of
C<readable> are extended so that it is signaled when a C<connect> or
C<accept> call will not block. Allowing applications to block on
network I/O in a controlled fashion is an important use of the wait
functions.
An outstanding problem with the interface documented here is that it
does not guarantee that a socket will still be readable or writable at
the time the application actually attempts I/O, nor does it indicate
I<how many> bytes may be read or written without blocking.
A better approach might be to do asynchronous I/O, and have
C<readable> and C<writable> return an Event that is set when the I/O
operation completes. I hesitate to specify such an interface until
there is more definition for file handles and asynchronous I/O in
Perl6.
=head2 Wait functions
C<wait_all> and C<wait_one> are generalizations of the C<select>(2)
Unix system call and the C<WaitForMultipleObjects> Win32 call.
It would seem natural to pass locked variables directly to the wait
functions
wait_all($a, ...
The problem with this is that there is no way to indicate whether the
function is to wait for a lock on I<$a>, or wait for (say) an Event
that I<$a> refers to. Instead, the wait functions take references; to
wait on a locked variable, write
wait_all(\$a, ...
The wait functions may seem overdone; however, applications really do
need these features, and they can be I<very> difficult to implement
without language support. For example, C<select>(2) doesn't work with
file descriptors for the console, and C<WaitForMultipleObjects>
doesn't work with sockets. I have direct experience with the
difficulty of programming around these deficiencies.
=head2 Timer
There are two kinds of timers: relative and absolute. Obviously, you
can always build one kind out of the other, but I wanted to
distinguish them with different constructors. I named the constructors
C<delay> and C<alarm>, respectively. These are short, and read fairly
naturally.
=head2 C<this Thread>
C++ partisans will get brain freeze reading code like
my $thread = this Thread;
but that's not why I traded in C<self> for C<this>. Really, it's not.
I did it because it reads more naturally to me.
=head1 REFERENCES
RFC 1: Implementation of Threads in Perl
RFC 27: Coroutines for Perl
RFC 31: Subroutines: Co-routines
RFC 47: Universal Asynchronous I/O
RFC 178: Lightweight Threads
Threads.pm
PThreads info page
