txt: ## concurrency.md
  Concurrency
  
  Concurrency and asynchronous programming
  
  In common with most modern programming languages, Raku is designed to support parallelism, asynchronicity and [concurrency](https://en.wikipedia.org/wiki/Concurrent_computing). Parallelism is about doing multiple things at once. *Asynchronous programming*, which is sometimes called event driven or reactive programming, is about supporting changes in the program flow caused by events triggered elsewhere in the program. Finally, concurrency is about the coordination of access and modification of some shared resources.
  
  The aim of the Raku concurrency design is to provide a high-level, composable and consistent interface, regardless of how a virtual machine may implement it for a particular operating system, through layers of facilities as described below.
  
  Additionally, certain Raku features may implicitly operate in an asynchronous fashion, so in order to ensure predictable interoperation with these features, user code should, where possible, avoid the lower level concurrency APIs (e.g., [`Thread`](/type/Thread) and [`Scheduler`](/type/Scheduler)) and use the higher-level interfaces.
  
  # [High-level APIs](#Concurrency "go to top of document")[§](#High-level_APIs "direct link")
  
  ## [Promises](#Concurrency "go to top of document")[§](#Promises "direct link")
  
  A [`Promise`](/type/Promise) (also called *future* in other programming environments) encapsulates the result of a computation that may not have completed or even started at the time the promise is obtained. A [`Promise`](/type/Promise) starts from a `Planned` status and can result in either a `Kept` status, meaning the promise has been successfully completed, or a `Broken` status meaning that the promise has failed. Usually this is much of the functionality that user code needs to operate in a concurrent or asynchronous manner.
  
  ```raku
  my $p1 = Promise.new;
  say $p1.status;         # OUTPUT: «Planned␤»
  $p1.keep('Result');
  say $p1.status;         # OUTPUT: «Kept␤»
  say $p1.result;         # OUTPUT: «Result␤»
                          # (since it has been kept, a result is available!)
  
  my $p2 = Promise.new;
  $p2.break('oh no');
  say $p2.status;         # OUTPUT: «Broken␤»
  say $p2.result;         # dies, because the promise has been broken
  CATCH { default { say .^name, ': ', .Str } };
  # OUTPUT: «X::AdHoc+{X::Promise::Broken}: oh no␤»
  
  ```
  
  Promises gain much of their power by being composable, for example by chaining, usually by the [then](/type/Promise#method_then) method:
  
  ```raku
  my $promise1 = Promise.new();
  my $promise2 = $promise1.then(
      -> $v { say $v.result; "Second Result" }
  );
  $promise1.keep("First Result");
  say $promise2.result;   # OUTPUT: «First Result␤Second Result␤»
  ```
  
  Here the [then](/type/Promise#method_then) method schedules code to be executed when the first [`Promise`](/type/Promise) is kept or broken, itself returning a new [`Promise`](/type/Promise) which will be kept with the result of the code when it is executed (or broken if the code fails). `keep` changes the status of the promise to `Kept` setting the result to the positional argument. `result` blocks the current thread of execution until the promise is kept or broken, if it was kept then it will return the result (that is the value passed to `keep`), otherwise it will throw an exception based on the value passed to `break`. The latter behavior is illustrated with:
  
  ```raku
  my $promise1 = Promise.new();
  my $promise2 = $promise1.then(-> $v { say "Handled but : "; say $v.result});
  $promise1.break("First Result");
  try $promise2.result;
  say $promise2.cause;        # OUTPUT: «Handled but : ␤First Result␤»
  ```
  
  Here the `break` will cause the code block of the `then` to throw an exception when it calls the `result` method on the original promise that was passed as an argument, which will subsequently cause the second promise to be broken, raising an exception in turn when its result is taken. The actual [`Exception`](/type/Exception) object will then be available from `cause`. If the promise had not been broken `cause` would raise an [`X::Promise::CauseOnlyValidOnBroken`](/type/X/Promise/CauseOnlyValidOnBroken) exception.
  
  A [`Promise`](/type/Promise) can also be scheduled to be automatically kept at a future time:
  
  ```raku
  my $promise1 = Promise.in(5);
  my $promise2 = $promise1.then(-> $v { say $v.status; 'Second Result' });
  say $promise2.result;
  ```
  
  The [method in](/type/Promise#method_in) creates a new promise and schedules a new task to call `keep` on it no earlier than the supplied number of seconds, returning the new [`Promise`](/type/Promise) object.
  
  A very frequent use of promises is to run a piece of code, and keep the promise once it returns successfully, or break it when the code dies. The [start method](/type/Promise#method_start) provides a shortcut for that:
  
  ```raku
  my $promise = Promise.start(
      { my $i = 0; for 1 .. 10 { $i += $_ }; $i}
  );
  say $promise.result;    # OUTPUT: «55␤»
  ```
  
  Here the `result` of the promise returned is the value returned from the code. Similarly if the code fails (and the promise is thus broken), then `cause` will be the [`Exception`](/type/Exception) object that was thrown:
  
  ```raku
  my $promise = Promise.start({ die "Broken Promise" });
  try $promise.result;
  say $promise.cause;
  ```
  
  This is considered to be such a commonly required pattern that it is also provided as a keyword:
  
  ```raku
  my $promise = start {
      my $i = 0;
      for 1 .. 10 {
          $i += $_
      }
      $i
  }
  my $result = await $promise;
  say $result;
  ```
  
  The subroutine [await](/type/Promise#sub_await) is almost equivalent to calling `result` on the promise object returned by `start` but it will also take a list of promises and return the result of each:
  
  ```raku
  my $p1 = start {
      my $i = 0;
      for 1 .. 10 {
          $i += $_
      }
      $i
  };
  my $p2 = start {
      my $i = 0;
      for 1 .. 10 {
          $i -= $_
      }
      $i
  };
  my @result = await $p1, $p2;
  say @result;            # OUTPUT: «[55 -55]␤»
  ```
  
  In addition to `await`, two class methods combine several [`Promise`](/type/Promise) objects into a new promise: `allof` returns a promise that is kept when all the original promises are kept or broken:
  
  ```raku
  my $promise = Promise.allof(
      Promise.in(2),
      Promise.in(3)
  );
  
  await $promise;
  say "All done"; # Should be not much more than three seconds later
  ```
  
  And `anyof` returns a new promise that will be kept when any of the original promises is kept or broken:
  
  ```raku
  my $promise = Promise.anyof(
      Promise.in(3),
      Promise.in(8600)
  );
  
  await $promise;
  say "All done"; # Should be about 3 seconds later
  ```
  
  Unlike `await` however the results of the original kept promises are not available without referring to the original, so these are more useful when the completion or otherwise of the tasks is more important to the consumer than the actual results, or when the results have been collected by other means. You may, for example, want to create a dependent Promise that will examine each of the original promises:
  
  ```raku
  my @promises;
  for 1..5 -> $t {
      push @promises, start {
          sleep $t;
          Bool.pick;
      };
  }
  say await Promise.allof(@promises).then({ so all(@promises>>.result) });
  ```
  
  Which will give True if all of the promises were kept with True, False otherwise.
  
  If you are creating a promise that you intend to keep or break yourself then you probably don't want any code that might receive the promise to inadvertently (or otherwise) keep or break the promise before you do. For this purpose there is the [method vow](/type/Promise#method_vow), which returns a Vow object which becomes the only mechanism by which the promise can be kept or broken. If an attempt to keep or break the Promise is made directly then the exception [`X::Promise::Vowed`](/type/X/Promise/Vowed) will be thrown, as long as the vow object is kept private, the status of the promise is safe:
  
  ```raku
  sub get_promise {
      my $promise = Promise.new;
      my $vow = $promise.vow;
      Promise.in(10).then({$vow.keep});
      $promise;
  }
  
  my $promise = get_promise();
  
  # Will throw an exception
  # "Access denied to keep/break this Promise; already vowed"
  $promise.keep;
  CATCH { default { say .^name, ': ', .Str } };
  # OUTPUT: «X::Promise::Vowed: Access denied to keep/break this Promise; already vowed␤»
  ```
  
  The methods that return a promise that will be kept or broken automatically such as `in` or `start` will do this, so it is not necessary to do it for these.
  
  ## [Supplies](#Concurrency "go to top of document")[§](#Supplies "direct link")
  
  A [`Supply`](/type/Supply) is an asynchronous data streaming mechanism that can be consumed by one or more consumers simultaneously in a manner similar to "events" in other programming languages and can be seen as enabling *event driven* or reactive designs.
  
  At its simplest, a [`Supply`](/type/Supply) is a message stream that can have multiple subscribers created with the method `tap` on to which data items can be placed with `emit`.
  
  The [`Supply`](/type/Supply) can either be `live` or `on-demand`. A `live` supply is like a TV broadcast: those who tune in don't get previously emitted values. An `on-demand` broadcast is like Netflix: everyone who starts streaming a movie (taps a supply), always starts it from the beginning (gets all the values), regardless of how many people are watching it right now. Note that no history is kept for `on-demand` supplies, instead, the `supply` block is run for each tap of the supply.
  
  A `live` [`Supply`](/type/Supply) is created by the [`Supplier`](/type/Supplier) factory, each emitted value is passed to all the active tappers as they are added:
  
  ```raku
  my $supplier = Supplier.new;
  my $supply   = $supplier.Supply;
  
  $supply.tap( -> $v { say $v });
  
  for 1 .. 10 {
      $supplier.emit($_);
  }
  ```
  
  Note that the `tap` is called on a [`Supply`](/type/Supply) object created by the [`Supplier`](/type/Supplier) and new values are emitted on the [`Supplier`](/type/Supplier).
  
  An `on-demand` [`Supply`](/type/Supply) is created by the `supply` keyword:
  
  ```raku
  my $supply = supply {
      for 1 .. 10 {
          emit($_);
      }
  }
  $supply.tap( -> $v { say $v });
  ```
  
  In this case the code in the supply block is executed every time the [`Supply`](/type/Supply) returned by `supply` is tapped, as demonstrated by:
  
  ```raku
  my $supply = supply {
      for 1 .. 10 {
          emit($_);
      }
  }
  $supply.tap( -> $v { say "First : $v" });
  $supply.tap( -> $v { say "Second : $v" });
  ```
  
  The `tap` method returns a [`Tap`](/type/Tap) object which can be used to obtain information about the tap and also to turn it off when we are no longer interested in the events:
  
  ```raku
  my $supplier = Supplier.new;
  my $supply   = $supplier.Supply;
  
  my $tap = $supply.tap( -> $v { say $v });
  
  $supplier.emit("OK");
  $tap.close;
  $supplier.emit("Won't trigger the tap");
  ```
  
  Calling `done` on the supply object calls the `done` callback that may be specified for any taps, but does not prevent any further events being emitted to the stream, or taps receiving them.
  
  The method `interval` returns a new `on-demand` supply which periodically emits a new event at the specified interval. The data that is emitted is an integer starting at 0 that is incremented for each event. The following code outputs 0 .. 5 :
  
  ```raku
  my $supply = Supply.interval(2);
  $supply.tap(-> $v { say $v });
  sleep 10;
  ```
  
  A second argument can be supplied to `interval` which specifies a delay in seconds before the first event is fired. Each tap of a supply created by `interval` has its own sequence starting from 0, as illustrated by the following:
  
  ```raku
  my $supply = Supply.interval(2);
  $supply.tap(-> $v { say "First $v" });
  sleep 6;
  $supply.tap(-> $v { say "Second $v"});
  sleep 10;
  ```
  
  A live [`Supply`](/type/Supply) that keeps values until first tapped can be created with [`Supplier::Preserving`](/type/Supplier/Preserving).
  
  ### [`whenever`](#Concurrency "go to top of document")[§](#whenever "direct link")
  
  The `whenever` keyword can be used in supply blocks or in react blocks. From the 6.d version, it needs to be used within the lexical scope of them. It introduces a block of code that will be run when prompted by an asynchronous event that it specifies - that could be a [`Supply`](/type/Supply), a [`Channel`](/type/Channel), a [`Promise`](/type/Promise) or an [`Iterable`](/type/Iterable).
  
  Please note that one should keep the code inside the `whenever` as small as possible, as only one `whenever` block will be executed at any time. One can use a `start` block inside the `whenever` block to run longer running code.
  
  In this example we are watching two supplies.
  
  ```raku
  my $bread-supplier = Supplier.new;
  my $vegetable-supplier = Supplier.new;
  
  my $supply = supply {
      whenever $bread-supplier.Supply {
          emit("We've got bread: " ~ $_);
      };
      whenever $vegetable-supplier.Supply {
          emit("We've got a vegetable: " ~ $_);
      };
  }
  $supply.tap( -> $v { say "$v" });
  
  $vegetable-supplier.emit("Radish");   # OUTPUT: «We've got a vegetable: Radish␤»
  $bread-supplier.emit("Thick sliced"); # OUTPUT: «We've got bread: Thick sliced␤»
  $vegetable-supplier.emit("Lettuce");  # OUTPUT: «We've got a vegetable: Lettuce␤»
  
  ```
  
  ### [`react`](#Concurrency "go to top of document")[§](#react "direct link")
  
  The `react` keyword introduces a block of code containing one or more `whenever` keywords to watch asynchronous events. The main difference between a supply block and a react block is that the code in a react block runs where it appears in the code flow, whereas a supply block has to be tapped before it does anything.
  
  Another difference is that a supply block can be used without the `whenever` keyword, but a react block requires at least one `whenever` to be of any real use.
  
  ```raku
  react {
      whenever Supply.interval(2) -> $v {
          say $v;
          done() if $v == 4;
      }
  }
  ```
  
  Here the `whenever` keyword uses [`.act`](/type/Supply#method_act) to create a tap on the [`Supply`](/type/Supply) from the provided block. The `react` block is exited when `done()` is called in one of the taps. Using `last` to exit the block would produce an error indicating that it's not really a loop construct.
  
  An `on-demand` [`Supply`](/type/Supply) can also be created from a list of values that will be emitted in turn, thus the first `on-demand` example could be written as:
  
  ```raku
  react {
      whenever Supply.from-list(1..10) -> $v {
          say $v;
      }
  }
  ```
  
  ### [Transforming supplies](#Concurrency "go to top of document")[§](#Transforming_supplies "direct link")
  
  An existing supply object can be filtered or transformed, using the methods `grep` and `map` respectively, to create a new supply in a manner like the similarly named list methods: `grep` returns a supply such that only those events emitted on the source stream for which the `grep` condition is true is emitted on the second supply:
  
  ```raku
  my $supplier = Supplier.new;
  my $supply = $supplier.Supply;
  $supply.tap(-> $v { say "Original : $v" });
  my $odd_supply = $supply.grep({ $_ % 2 });
  $odd_supply.tap(-> $v { say "Odd : $v" });
  my $even_supply = $supply.grep({ not $_ % 2 });
  $even_supply.tap(-> $v { say "Even : $v" });
  for 0 .. 10 {
      $supplier.emit($_);
  }
  ```
  
  `map` returns a new supply such that for each item emitted to the original supply a new item which is the result of the expression passed to the `map` is emitted:
  
  ```raku
  my $supplier = Supplier.new;
  my $supply = $supplier.Supply;
  $supply.tap(-> $v { say "Original : $v" });
  my $half_supply = $supply.map({ $_ / 2 });
  $half_supply.tap(-> $v { say "Half : $v" });
  for 0 .. 10 {
      $supplier.emit($_);
  }
  ```
  
  ### [Ending a supply](#Concurrency "go to top of document")[§](#Ending_a_supply "direct link")
  
  If you need to have an action that runs when the supply finishes, you can do so by setting the `done` and `quit` options in the call to `tap`:
  
  ```raku
  $supply.tap: { ... },
      done => { say 'Job is done.' },
      quit => {
          when X::MyApp::Error { say "App Error: ", $_.message }
      };
  
  ```
  
  The `quit` block works very similar to a `CATCH`. If the exception is marked as seen by a `when` or `default` block, the exception is caught and handled. Otherwise, the exception continues to up the call tree (i.e., the same behavior as when `quit` is not set).
  
  ### [Phasers in a supply or react block](#Concurrency "go to top of document")[§](#Phasers_in_a_supply_or_react_block "direct link")
  
  If you are using the `react` or `supply` block syntax with `whenever`, you can add phasers within your `whenever` blocks to handle the `done` and `quit` messages from the tapped supply:
  
  ```raku
  react {
      whenever $supply {
          ...; # your usual supply tap code here
          LAST { say 'Job is done.' }
          QUIT { when X::MyApp::Error { say "App Error: ", $_.message } }
      }
  }
  
  ```
  
  The behavior here is the same as setting `done` and `quit` on `tap`.
  
  ## [Channels](#Concurrency "go to top of document")[§](#Channels "direct link")
  
  A [`Channel`](/type/Channel) is a thread-safe queue that can have multiple readers and writers that could be considered to be similar in operation to a "fifo" or named pipe except it does not enable inter-process communication. It should be noted that, being a true queue, each value sent to the [`Channel`](/type/Channel) will only be available to a single reader on a first read, first served basis: if you want multiple readers to be able to receive every item sent you probably want to consider a [`Supply`](/type/Supply).
  
  An item is queued onto the [`Channel`](/type/Channel) with the [method send](/type/Channel#method_send), and the [method receive](/type/Channel#method_receive) removes an item from the queue and returns it, blocking until a new item is sent if the queue is empty:
  
  ```raku
  my $channel = Channel.new;
  $channel.send('Channel One');
  say $channel.receive;  # OUTPUT: «Channel One␤»
  ```
  
  If the channel has been closed with the [method close](/type/Channel#method_close) then any `send` will cause the exception [`X::Channel::SendOnClosed`](/type/X/Channel/SendOnClosed) to be thrown, and a `receive` will throw an [`X::Channel::ReceiveOnClosed`](/type/X/Channel/ReceiveOnClosed).
  
  The [method list](/type/Channel#method_list) returns all the items on the [`Channel`](/type/Channel) and will block until further items are queued unless the channel is closed:
  
  ```raku
  my $channel = Channel.new;
  await (^10).map: -> $r {
      start {
          sleep $r;
          $channel.send($r);
      }
  }
  $channel.close;
  for $channel.list -> $r {
      say $r;
  }
  ```
  
  There is also the non-blocking [method poll](/type/Channel#method_poll) that returns an available item from the channel or [`Nil`](/type/Nil) if there is no item or the channel is closed. This does mean that the channel must be checked to determine whether it is closed:
  
  ```raku
  my $c = Channel.new;
  
  # Start three Promises that sleep for 1..3 seconds, and then
  # send a value to our Channel
  ^3 .map: -> $v {
      start {
          sleep 3 - $v;
          $c.send: "$v from thread {$*THREAD.id}";
      }
  }
  
  # Wait 3 seconds before closing the channel
  Promise.in(3).then: { $c.close }
  
  # Continuously loop and poll the channel, until it's closed
  my $is-closed = $c.closed;
  loop {
      if $c.poll -> $item {
          say "$item received after {now - INIT now} seconds";
      }
      elsif $is-closed {
          last;
      }
  
      say 'Doing some unrelated things...';
      sleep .6;
  }
  
  # Doing some unrelated things...
  # Doing some unrelated things...
  # 2 from thread 5 received after 1.2063182 seconds
  # Doing some unrelated things...
  # Doing some unrelated things...
  # 1 from thread 4 received after 2.41117376 seconds
  # Doing some unrelated things...
  # 0 from thread 3 received after 3.01364461 seconds
  # Doing some unrelated things...
  ```
  
  The [method closed](/type/Channel#method_closed) returns a [`Promise`](/type/Promise) that will be kept (and consequently will evaluate to True in a Boolean context) when the channel is closed.
  
  The `.poll` method can be used in combination with `.receive` method, as a caching mechanism where lack of value returned by `.poll` is a signal that more values need to be fetched and loaded into the channel:
  
  ```raku
  sub get-value {
      return $c.poll // do { start replenish-cache; $c.receive };
  }
  
  sub replenish-cache {
      for ^20 {
          $c.send: $_ for slowly-fetch-a-thing();
      }
  }
  
  ```
  
  Channels can be used in place of the [`Supply`](/type/Supply) in the `whenever` of a `react` block described earlier:
  
  ```raku
  my $channel = Channel.new;
  my $p = start {
      react {
          whenever $channel {
              say $_;
          }
      }
  }
  
  await (^10).map: -> $r {
      start {
          sleep $r;
          $channel.send($r);
      }
  }
  
  $channel.close;
  await $p;
  
  ```
  
  It is also possible to obtain a [`Channel`](/type/Channel) from a [`Supply`](/type/Supply) using the [Channel method](/type/Supply#method_Channel) which returns a [`Channel`](/type/Channel) which is fed by a `tap` on the [`Supply`](/type/Supply):
  
  ```raku
  my $supplier = Supplier.new;
  my $supply   = $supplier.Supply;
  my $channel = $supply.Channel;
  
  my $p = start {
      react  {
          whenever $channel -> $item {
              say "via Channel: $item";
          }
      }
  }
  
  await (^10).map: -> $r {
      start {
          sleep $r;
          $supplier.emit($r);
      }
  }
  
  $supplier.done;
  await $p;
  ```
  
  [`Channel`](/type/Channel) will return a different [`Channel`](/type/Channel) fed with the same data each time it is called. This could be used, for instance, to fan-out a [`Supply`](/type/Supply) to one or more [`Channel`](/type/Channel)s to provide for different interfaces in a program.
  
  ## [Proc::Async](#Concurrency "go to top of document")[§](#Proc::Async "direct link")
  
  [`Proc::Async`](/type/Proc/Async) builds on the facilities described to run and interact with an external program asynchronously:
  
  ```raku
  my $proc = Proc::Async.new('echo', 'foo', 'bar');
  
  $proc.stdout.tap(-> $v { print "Output: $v" });
  $proc.stderr.tap(-> $v { print "Error:  $v" });
  
  say "Starting...";
  my $promise = $proc.start;
  
  await $promise;
  say "Done.";
  
  # Output:
  # Starting...
  # Output: foo bar
  # Done.
  ```
  
  The path to the command as well as any arguments to the command are supplied to the constructor. The command will not be executed until [start](/type/Proc/Async#method_start) is called, which will return a [`Promise`](/type/Promise) that will be kept when the program exits. The standard output and standard error of the program are available as [`Supply`](/type/Supply) objects from the methods [stdout](/type/Proc/Async#method_stdout) and [stderr](/type/Proc/Async#method_stderr) respectively which can be tapped as required.
  
  If you want to write to the standard input of the program you can supply the `:w` adverb to the constructor and use the methods [write](/type/Proc/Async#method_write), [print](/type/Proc/Async#method_print) or [say](/type/Proc/Async#method_say) to write to the opened pipe once the program has been started:
  
  ```raku
  my $proc = Proc::Async.new(:w, 'grep', 'foo');
  
  $proc.stdout.tap(-> $v { print "Output: $v" });
  
  say "Starting...";
  my $promise = $proc.start;
  
  $proc.say("this line has foo");
  $proc.say("this one doesn't");
  
  $proc.close-stdin;
  await $promise;
  say "Done.";
  
  # Output:
  # Starting...
  # Output: this line has foo
  # Done.
  ```
  
  Some programs (such as `grep` without a file argument in this example, ) won't exit until their standard input is closed so [close-stdin](/type/Proc/Async#method_close-stdin) can be called when you are finished writing to allow the [`Promise`](/type/Promise) returned by `start` to be kept.
  
  # [Low-level APIs](#Concurrency "go to top of document")[§](#Low-level_APIs "direct link")
  
  ## [Threads](#Concurrency "go to top of document")[§](#Threads "direct link")
  
  The lowest level interface for concurrency is provided by [`Thread`](/type/Thread). A thread can be thought of as a piece of code that may eventually be run on a processor, the arrangement for which is made almost entirely by the virtual machine and/or operating system. Threads should be considered, for all intents, largely un-managed and their direct use should be avoided in user code.
  
  A thread can either be created and then actually run later:
  
  ```raku
  my $thread = Thread.new(code => { for  1 .. 10  -> $v { say $v }});
  # ...
  $thread.run;
  ```
  
  Or can be created and run at a single invocation:
  
  ```raku
  my $thread = Thread.start({ for  1 .. 10  -> $v { say $v }});
  ```
  
  In both cases the completion of the code encapsulated by the [`Thread`](/type/Thread) object can be waited on with the `finish` method which will block until the thread completes:
  
  ```raku
  $thread.finish;
  
  ```
  
  Beyond that there are no further facilities for synchronization or resource sharing which is largely why it should be emphasized that threads are unlikely to be useful directly in user code.
  
  ## [Schedulers](#Concurrency "go to top of document")[§](#Schedulers "direct link")
  
  The next level of the concurrency API is supplied by classes that implement the interface defined by the role [`Scheduler`](/type/Scheduler). The intent of the scheduler interface is to provide a mechanism to determine which resources to use to run a particular task and when to run it. The majority of the higher level concurrency APIs are built upon a scheduler and it may not be necessary for user code to use them at all, although some methods such as those found in [`Proc::Async`](/type/Proc/Async), [`Promise`](/type/Promise) and [`Supply`](/type/Supply) allow you to explicitly supply a scheduler.
  
  The current default global scheduler is available in the variable `$*SCHEDULER`.
  
  The primary interface of a scheduler (indeed the only method required by the [`Scheduler`](/type/Scheduler) interface) is the `cue` method:
  
  ```raku
  method cue(:&code, Instant :$at, :$in, :$every, :$times = 1; :&catch)
  ```
  
  This will schedule the [`Callable`](/type/Callable) in `&code` to be executed in the manner determined by the adverbs (as documented in [`Scheduler`](/type/Scheduler)) using the execution scheme as implemented by the scheduler. For example:
  
  ```raku
  my $i = 0;
  my $cancellation = $*SCHEDULER.cue({ say $i++}, every => 2 );
  sleep 20;
  ```
  
  Assuming that the `$*SCHEDULER` hasn't been changed from the default, will print the numbers 0 to 10 approximately (i.e with operating system scheduling tolerances) every two seconds. In this case the code will be scheduled to run until the program ends normally, however the method returns a [`Cancellation`](/type/Cancellation) object which can be used to cancel the scheduled execution before normal completion:
  
  ```raku
  my $i = 0;
  my $cancellation = $*SCHEDULER.cue({ say $i++}, every => 2 );
  sleep 10;
  $cancellation.cancel;
  sleep 10;
  ```
  
  should only output 0 to 5.
  
  Despite the apparent advantage the [`Scheduler`](/type/Scheduler) interface provides over that of [`Thread`](/type/Thread) all of functionality is available through higher level interfaces and it shouldn't be necessary to use a scheduler directly, except perhaps in the cases mentioned above where a scheduler can be supplied explicitly to certain methods.
  
  A library may wish to provide an alternative scheduler implementation if it has special requirements, for instance a UI library may want all code to be run within a single UI thread, or some custom priority mechanism may be required, however the implementations provided as standard and described below should suffice for most user code.
  
  ### [ThreadPoolScheduler](#Concurrency "go to top of document")[§](#ThreadPoolScheduler "direct link")
  
  The [`ThreadPoolScheduler`](/type/ThreadPoolScheduler) is the default scheduler, it maintains a pool of threads that are allocated on demand, creating new ones as necessary.
  
  Rakudo allows the maximum number of threads allowed in the default scheduler to be set by the environment variable `RAKUDO_MAX_THREADS` at the time the program is started.
  
  If the maximum is exceeded then `cue` may queue the code until a thread becomes available.
  
  ### [CurrentThreadScheduler](#Concurrency "go to top of document")[§](#CurrentThreadScheduler "direct link")
  
  The [`CurrentThreadScheduler`](/type/CurrentThreadScheduler) is a very simple scheduler that will always schedule code to be run straight away on the current thread. The implication is that `cue` on this scheduler will block until the code finishes execution, limiting its utility to certain special cases such as testing.
  
  ## [Locks](#Concurrency "go to top of document")[§](#Locks "direct link")
  
  The class [`Lock`](/type/Lock) provides the low level mechanism that protects shared data in a concurrent environment and is thus key to supporting thread-safety in the high level API, this is sometimes known as a "Mutex" in other programming languages. Because the higher level classes ([`Promise`](/type/Promise), [`Supply`](/type/Supply) and [`Channel`](/type/Channel)) use a [`Lock`](/type/Lock) where required it is unlikely that user code will need to use a [`Lock`](/type/Lock) directly.
  
  The primary interface to [`Lock`](/type/Lock) is the method [protect](/type/Lock#method_protect) which ensures that a block of code (commonly called a "critical section") is only executed in one thread at a time:
  
  ```raku
  my $lock = Lock.new;
  
  my $a = 0;
  
  await (^10).map: {
      start {
          $lock.protect({
              my $r = rand;
              sleep $r;
              $a++;
          });
      }
  }
  
  say $a; # OUTPUT: «10␤»
  ```
  
  `protect` returns whatever the code block returns.
  
  Because `protect` will block any threads that are waiting to execute the critical section the code should be as quick as possible.
  
  # [Safety concerns](#Concurrency "go to top of document")[§](#Safety_concerns "direct link")
  
  Some shared data concurrency issues are less obvious than others. For a good general write-up on this subject see this [blog post](https://6guts.wordpress.com/2014/04/17/racing-to-writeness-to-wrongness-leads/).
  
  One particular issue of note is when container autovivification or extension takes place. When an [`Array`](/type/Array) or a [`Hash`](/type/Hash) entry is initially assigned the underlying structure is altered and that operation is not async safe. For example, in this code:
  
  ```raku
  my @array;
  my $slot := @array[20];
  $slot = 'foo';
  ```
  
  The third line is the critical section as that is when the array is extended. The simplest fix is to use a [`Lock`](/type/Lock) to protect the critical section. A possibly better fix would be to refactor the code so that sharing a container is not necessary.
  