txt: ## thread.md
  class Thread
  
  Concurrent execution of code (low-level)
  
  ```raku
  class Thread {}
  ```
  
  A [thread](https://en.wikipedia.org/wiki/Thread_%28computing%29) 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`](/type/Promise#method_start), which also runs in parallel and returns a [`Promise`](/type/Promise).
  
  ```raku
  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](#class_Thread "go to top of document")[§](#Methods "direct link")
  
  ## [method new](#class_Thread "go to top of document")[§](#method_new "direct link")
  
  ```raku
  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](#class_Thread "go to top of document")[§](#method_start "direct link")
  
  ```raku
  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](#class_Thread "go to top of document")[§](#method_run "direct link")
  
  ```raku
  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](#class_Thread "go to top of document")[§](#method_id "direct link")
  
  ```raku
  method id(Thread:D: --> Int:D)
  ```
  
  Returns a numeric, unique thread identifier.
  
  ## [method finish](#class_Thread "go to top of document")[§](#method_finish "direct link")
  
  ```raku
  method finish(Thread:D:)
  ```
  
  Waits for the thread to finish. This is called [join](#method_join) in other programming systems.
  
  ## [method join](#class_Thread "go to top of document")[§](#method_join "direct link")
  
  ```raku
  method join(Thread:D:)
  ```
  
  Waits for the thread to finish.
  
  ## [method yield](#class_Thread "go to top of document")[§](#method_yield "direct link")
  
  ```raku
  method yield(Thread:U:)
  ```
  
  Tells the scheduler to prefer another thread for now.
  
  ```raku
  Thread.yield;
  ```
  
  ## [method app\_lifetime](#class_Thread "go to top of document")[§](#method_app_lifetime "direct link")
  
  ```raku
  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.
  
  ```raku
  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](#class_Thread "go to top of document")[§](#method_name "direct link")
  
  ```raku
  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.
  
  ```raku
  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](#class_Thread "go to top of document")[§](#method_Numeric "direct link")
  
  ```raku
  method Numeric(Thread:D: --> Int:D)
  ```
  
  Returns a numeric, unique thread identifier, i.e. the same as [id](#method_id).
  
  ## [method Str](#class_Thread "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  method Str(Thread:D: --> Str:D)
  ```
  
  Returns a string which contains the invocants [thread id](#method_id) and [name](#method_name).
  
  ```raku
  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](#class_Thread "go to top of document")[§](#method_is-initial-thread "direct link")
  
  ```raku
  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.
  
  ```raku
  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](#class_Thread "go to top of document")[§](#Routines "direct link")
  
  ## [sub full-barrier](#class_Thread "go to top of document")[§](#sub_full-barrier "direct link")
  
  ```raku
  sub full-barrier()
  ```
  
  Performs a full memory barrier, preventing re-ordering of reads/writes. Required for implementing some lock-free data structures and algorithms.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Thread`
  
  
  
  raku-type-graph
  
  
  
  Thread
  Thread
  
  
  Any
  Any
  
  
  Thread->Any
  
  
  
  Mu
  Mu
  
  
  Any->Mu
  
  [Expand chart above](/assets/typegraphs/Thread.svg)
  