class Thread {}

A thread is a sequence of instructions that can (potentially) run in parallel to others. Class Thread provides a bit of abstraction over threads provided by the underlying virtual machines (which in turn might or might not be operating system threads).

Since threads are fairly low-level, most applications should use other primitives, like start, which also runs in parallel and returns a Promise.

my @threads = (^10).map: {
    Thread.start(
        name => "Sleepsorter $_",
        sub {
            my $rand = (^10).pick;
            sleep $rand;
            say $rand;
        },
    );
}
 
.finish for @threads;

The current thread is available in the dynamic variable $*THREAD.

Methods

method new

method new(:&code!, Bool :$app_lifetime = False, Str :$name = '<anon>' --> Thread:D)

Creates and returns a new Thread, without starting it yet. &code is the code that will be run in a separate thread.

$name is a user-specified string that identifies the thread.

If $app_lifetime is set to True, then the thread is killed when the main thread of the process terminates. If set to False, the process will only terminate when the thread has finished.

method start

method start(Thread:U: &code, Bool :$app_lifetime = False, Str :$name = '<anon>' --> Thread:D)

Creates, runs and returns a new Thread. Note that it can (and often does) return before the thread's code has finished running.

method run

method run(Thread:D:)

Runs the thread, and returns the invocant. It is an error to run a thread that has already been started.

method id

method id(Thread:D: --> Int:D)

Returns a numeric, unique thread identifier.

method finish

method finish(Thread:D:)

Waits for the thread to finish. This is called join in other programming systems.

method join

method join(Thread:D:)

Waits for the thread to finish.

method yield

method yield(Thread:U:)

Tells the scheduler to prefer another thread for now.

Thread.yield;

method app_lifetime

method app_lifetime(Thread:D: --> Bool:D)

Returns False unless the named parameter :app_lifetime is specifically set to True during object creation. If the method returns False it means that the process will only terminate when the thread has finished while True means that the thread will be killed when the main thread of the process terminates.

my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }});
my $t2 = Thread.new(code => { for 1..5 -> $v { say $v }}, :app_lifetime);
 
say $t1.app_lifetime;                 # OUTPUT: «False␤» 
say $t2.app_lifetime;                 # OUTPUT: «True␤»

method name

method name(Thread:D: --> Str:D)

Returns the user defined string, which can optionally be set during object creation in order to identify the Thread, or '<anon>' if no such string was specified.

my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }});
my $t2 = Thread.new(code => { for 1..5 -> $v { say $v }}, name => 'my thread');
 
say $t1.name;                 # OUTPUT: «<anon>␤» 
say $t2.name;                 # OUTPUT: «my thread␤»

method Numeric

method Numeric(Thread:D: --> Int:D)

Returns a numeric, unique thread identifier, i.e. the same as id.

method Str

method Str(Thread:D: --> Str:D)

Returns a string which contains the invocants id and name.

my $t = Thread.new(code => { for 1..5 -> $v { say $v }}, name => 'calc thread');
say $t.Str;                           # OUTPUT: «Thread<3>(calc thread)␤»

method is-initial-thread

method is-initial-thread(--> Bool)

Returns a Bool indicating whether the current thread (if called as a class method) or the Thread object on which it is called, is the initial thread the program started on.

say Thread.is-initial-thread;    # True if this is the initial thread 
say $*THREAD.is-initial-thread;  # True if $*THREAD is the initial thread

Please note there is no guarantee that this is actually the main thread from the OS's point of view. Also note that if you need this other than from a pure introspection / debugging point of view, that there are probably better ways to achieve what you're trying to achieve.

Routines

sub full-barrier

sub full-barrier()

Performs a full memory barrier, preventing re-ordering of reads/writes. Required for implementing some lock-free data structures and algorithms.