Rules / Types, classes & roles / domain-specific

Thread Reference

Concurrent execution of code (low-level)

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method new #

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

Returns 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)

Returns 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 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.

method app_lifetime #

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

Returns 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.

method name #

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

Returns Str:D.

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

method Numeric #

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

Returns Int:D.

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

method Str #

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

Returns Str:D.

Returns a string which contains the invocants thread id and name.

method is-initial-thread #

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

Returns 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. 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

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.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

1 all-differ · 6 no-output · 2 not-runnable

class Thread {}

Not executed: the documentation states no expected output for this example.

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

.finish for @threads;

Not executed: the documentation states no expected output for this example.

Thread.yield;

Not executed: the documentation states no expected output for this example.

my $t1 = Thread.new(code => { for 1..5 -> $v { say $v }});
my $t2 = Thread.new(code => { for 1..5 -> $v { say $v }}, :app_lifetime);

Not executed: the documentation states no expected output for this example.

say $t1.app_lifetime;                 # OUTPUT: «False␤»
say $t2.app_lifetime;                 # OUTPUT: «True␤»

Neither engine can run this in isolation — the example depends on context from the surrounding text.

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');

Not executed: the documentation states no expected output for this example.

say $t1.name;                 # OUTPUT: «<anon>␤»
say $t2.name;                 # OUTPUT: «my thread␤»

Neither engine can run this in isolation — the example depends on context from the surrounding text.

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

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

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

Not executed: the documentation states no expected output for this example.