TITLE

Scheme for automatically assigning tasks to threads


SUBTITLE

role Scheduler {
    has &.uncaught_handler is rw
}


A scheduler is a piece of code that determines which resources to use to run
which task, and when. This role contains code that will be the same for all
kinds of schedulers.


Some operations for example on L<C<Proc::Async>|/type/Proc::Async>,
L<C<Promise>|/type/Promise>, L<C<Supply>|/type/Supply> allow you to specify a
scheduler explicitly; they generally expect those schedulers to follow the
interface defined by C<Scheduler>.


head

RW-Accessor for the handler that is caught for uncaught exceptions from the
code that is being scheduled and run.


method cue(&code, Instant :$at, :$in, :$every, :$times = 1; :&catch --> Cancellation)


Schedules a callable (C<&code>) for execution and returns an instantiated
L<C<Cancellation>|/type/Cancellation> object to cancel the scheduling of the
code for execution (which is especially important if you specify the C<:every
( time )> named parameter). The adverbs control when and how the code is run:


item

One should call the C<cancel> method on the returned L<C<Cancellation>|/type/Cancellation> object
to cancel the (possibly repeated) cueing of the code.


This is a method stub, should be re-implemented when subclassing.


root

CompUnit::PrecompilationRepository


role CompUnit::PrecompilationRepository


CompUnit::Repository


role CompUnit::Repository


Input/output related routines


role IO


Network socket


role IO::Socket


Information related to the build system


role Systemic


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

role Scheduler


Control access to shared resources by multiple threads


Protect your shared code, data or device access using semaphores. An example is
a printer manager managing a pool of printers without the need of storing print
jobs when all printers are occupied. The next job is just blocked until a
printer becomes available.


class print-manager {
  has Array $!printers;
  has Semaphore $!print-control;


method BUILD( Int:D :$nbr-printers ) {
  for ^$nbr-printers -> $pc {
    $!printers[$pc] = { :name{"printer-$pc"} };
  }


$!print-control .= new($nbr-printers);
}


method find-available-printer-and-print-it($job) { say "Is printed!"; }


method print( $print-job ) {
  $!print-control.acquire;


self.find-available-printer-and-print-it($print-job);


Another example is a protection around code updating sensitive data. In such a
case the semaphore is typically initialized to 1.


It is important to have a release on every exit of your program! While this is
obvious, it is easy to fall in traps such as throwing an exception caused by some
event. When the program dies there is no problem. When the exception is caught
your program might eventually come back to the acquire method and will hang
indefinitely.


Initialize the semaphore with the number of permitted accesses. E.g. when set to
2, program threads can pass the acquire method twice until it blocks on the
third time acquire is called.


Acquire access. When other threads have called the method before and the
number of permits are used up, the process blocks until threads passed before
releases the semaphore.


Same as acquire but will not block. Instead it returns C<True> if access is
permitted or C<False> otherwise.


Release the semaphore raising the number of permissions. Any blocked thread will
get access after that.


Member variable


class Attribute


Removal of a task from a Scheduler before normal completion


class Cancellation


Thread-safe queue for sending values from producers to consumers


class Channel


CompUnit


class CompUnit


CompUnit::Repository::FileSystem


class CompUnit::Repository::FileSystem


CompUnit::Repository::Installation


class CompUnit::Repository::Installation


Distribution related information


class Distro


Formal grammar made up of named regexes


class Grammar


Iterate over contents of files specified on command line


class IO::ArgFiles


Use multiple IO handles as if they were one


class IO::CatHandle


Opened file or stream


class IO::Handle


Asynchronous notification for file and directory changes





class IO::Notification


Changes in a file, produced by watch-file


class IO::Notification::Change


File or directory path


class IO::Path


IO::Path pre-loaded with IO::Spec::Cygwin


class IO::Path::Cygwin


IO::Path parts encapsulation


class IO::Path::Parts


IO::Path pre-loaded with IO::Spec::QNX


class IO::Path::QNX


IO::Path pre-loaded with IO::Spec::Unix


class IO::Path::Unix


IO::Path pre-loaded with IO::Spec::Win32


class IO::Path::Win32


Buffered inter-process string or binary stream


class IO::Pipe


Asynchronous socket in TCP or UDP


class IO::Socket::Async


A tap for listening TCP sockets


class IO::Socket::Async::ListenSocket


TCP Socket


class IO::Socket::INET


Platform specific operations on file and directory paths


class IO::Spec


Platform specific operations on file and directory paths for Cygwin


class IO::Spec::Cygwin


Platform specific operations on file and directory paths QNX


class IO::Spec::QNX


Platform specific operations on file and directory paths for POSIX


class IO::Spec::Unix


Platform specific operations on file and directory paths for Windows


class IO::Spec::Win32


Path to special I/O device


class IO::Special


Kernel related information


class Kernel


A low-level, re-entrant, mutual exclusion lock


class Lock


Condition variables used in locks


class Lock::ConditionVariable


Result of a successful regex match


class Match


Block in a Pod document


class Pod::Block


Verbatim code block in a Pod document


class Pod::Block::Code


Comment in a Pod document


class Pod::Block::Comment


Declarator block in a Pod document


class Pod::Block::Declarator


Named block in a Pod document


class Pod::Block::Named


Paragraph in a Pod document


class Pod::Block::Para


Table in a Pod document


class Pod::Block::Table


Pod definition list


class Pod::Defn


Pod formatting code


class Pod::FormattingCode


Heading in a Pod document


class Pod::Heading


Item in a Pod enumeration list


class Pod::Item


Running process (filehandle-based interface)


class Proc


Running process (asynchronous interface)


class Proc::Async


Status/result of an asynchronous computation


class Promise


String pattern


class Regex


Live Supply factory


class Supplier


Cached live Supply factory


class Supplier::Preserving


Asynchronous data stream with multiple subscribers


class Supply


Subscription to a Supply


class Tap


Concurrent execution of code (low-level)


class Thread


Scheduler that distributes work among a pool of threads


class ThreadPoolScheduler


Unicode related information


class Unicode


Raku Virtual Machine related information


class VM


class Semaphore


A mostly transparent container used for indirections


A C<Scalar> is an internal indirection, that is, a way to refer indirectly to a
value, which is, for most purposes, invisible during ordinary use of Raku. It is
the default container type associated with the C<$> sigil. A literal C<Scalar>
may be placed around any literal by enclosing the value in C<$(…)>. This
notation will appear in the output of a C<.raku> method in certain places where
it is important to note the presence of C<Scalar>s.


When a value is assigned to a C<$>-sigiled variable, the variable will
actually bind to a C<Scalar>, which in turn will bind to the value.
When a C<Scalar> is assigned to a C<$>-sigiled variable, the value
bound to by that C<Scalar> will be bound to the C<Scalar> which that
variable was bound to (a new one will be created if necessary.)


In addition, C<Scalar>s delegate all method calls to the value which they
contain. As such, C<Scalar>s are for the most part invisible. There is, however,
one important place where C<Scalar>s have a visible impact: a C<Scalar>
container will shield its content from
L<flattening|/language/subscripts#index-entry-flattening_> by most Raku core list
operations.


code

These C<Scalar> containers can also be created on the fly by assigning to an
L<anonymous scalar variable|/language/variables#The_$_variable>:


A C<$>-sigiled variable may be bound directly to a value with no
intermediate C<Scalar> using the binding operator C<:=>. You can
tell if this has been done by examining the output of the
introspective pseudo-method C<.VAR>:


my $a = 1;
$a.^name.say;     # OUTPUT: «Int␤»
$a.VAR.^name.say; # OUTPUT: «Scalar␤»
my $b := 1;
$b.^name.say;     # OUTPUT: «Int␤»
$b.VAR.^name.say; # OUTPUT: «Int␤»


This same thing happens when values are assigned to an element of
an L<C<Array>|/type/Array>, however, L<C<List>|/type/List>s directly contain their values:


my @a = 1, 2, 3;
@a[0].^name.say;            # OUTPUT: «Int␤»
@a[0].VAR.^name.say;        # OUTPUT: «Scalar␤»
[1, 2, 3][0].^name.say;     # OUTPUT: «Int␤»
[1, 2, 3][0].VAR.^name.say; # OUTPUT: «Scalar␤»
(1, 2, 3)[0].^name.say;     # OUTPUT: «Int␤»
(1, 2, 3)[0].VAR.^name.say; # OUTPUT: «Int␤»


Array elements may be bound directly to values using C<:=> as well; however,
this is discouraged as it may lead to confusion. Doing so will break exact
round-tripping of C<.raku> output – since L<C<Array>|/type/Array>s are assumed to place
C<Scalar>s around each element, C<Scalar>s are not denoted with C<$> in the
output of C<Array.raku>.


[1, $(2, 3)].raku.say;     # OUTPUT: «[1, (2, 3)]␤»
(1, $(2, 3)).raku.say;     # OUTPUT: «(1, $(2, 3))␤»


Binding a C<Scalar> to a C<$>-sigiled variable replaces the existing
C<Scalar> in that variable, if any, with the given C<Scalar>.
That means more than one variable may refer to the same C<Scalar>.
Because the C<Scalar> may be mutated, this makes it possible to
alter the value of both variables by altering only one of them:


my $a = 1;
my $b := $a;
$b = 2;
$a.say;       # OUTPUT: «2␤»


X<|Syntax,\ (sigilless scalar)>
Raku allows the use of constants with a
L<static single assignment (SSA)|https://en.wikipedia.org/wiki/Static_single_assignment_form>
style which bind directly to their value with no intervening C<Scalar>
container, even when assignment (C<=>) is used. They may be forced to use a
C<Scalar> by assigning a C<$>-sigiled variable to them, at which point, they
behave entirely like C<$>-sigiled variables.


my \c = 1;
c.^name.say;             # OUTPUT: «Int␤»
c.VAR.^name.say;         # OUTPUT: «Int␤»
my $a = 1;
my \d = $a;              # just "my \d = $ = 1" works, too
d.^name.say;             # OUTPUT: «Int␤»
d.VAR.^name.say;         # OUTPUT: «Scalar␤»
d = 2;                   # ok
c = 2;                   # fails
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Assignment::RO: Cannot modify an immutable Int␤»


A C<Scalar> can have its value changed using a hardware-supported atomic
compare and swap operation. This is useful when implementing lock free data
structures and algorithms. It may also be fetched and assigned to in an
"atomic" fashion, which ensures appropriate memory barriering and prevents
unwanted optimizations of memory accesses.


A C<Scalar> that will be used with an atomic operation should B<always> be
explicitly initialized with a value before any atomic operations are
performed upon it. This is to avoid races with lazy allocation and
auto-vivification. For example:


Will work in principle since an L<C<Array>|/type/Array> consists of C<Scalar> containers.
However, the container is only bound into the array upon initial assignment.
Therefore, there would be a race to do that binding. The C<Scalar> atomic
operations will never check for or do any such auto-vivification, so as to
make such bugs much more evident (rather than only observed under stress).


Returns the type constraint of the container.


my Cool $x = 42;
say $x.VAR.of;                  # OUTPUT: «(Cool)␤»


Returns the default value associated with the container.


my $x is default(666) = 42;
say $x.VAR.default;             # OUTPUT: «666␤»


Returns the name associated with the container.


my $x = 42;
say $x.VAR.name;                # OUTPUT: «$x␤»


my $*FOO = 42;
say $*FOO.VAR.dynamic;          # OUTPUT: «True␤»


Note that you have to use the C<VAR> method in order to get that information.


my $s is dynamic = [1, 2, 3];
say $s.dynamic;                          # OUTPUT: «False␤»  (wrong, don't do this)
say $s.VAR.dynamic;                      # OUTPUT: «True␤»   (correct approach)


multi atomic-assign($target is rw, $value)


role Scheduler

Methods

method uncaught_handler

method cue

method loads

See Also