.. _language-builtins-wse3:

Builtins for WSE-3
==================

This section documents CSL builtins that are only supported for WSE-3.

@set_control_task_table
-----------------------

Create a separate control task table.

Syntax
^^^^^^

.. code-block:: csl

   @set_control_task_table();
   @set_control_task_table(config);

Where:

* ``config`` is a comptime-known (anonymous) struct with the following
  optional fields:

  * ``instructions``
  * ``stride``

Example
^^^^^^^

.. code-block:: csl

   task foo() void {}
   task bar() void {}

   comptime {
     @bind_control_task(foo, @get_control_task_id(10));
     @bind_local_task(bar, @get_local_task_id(10));

     // Even though 'foo' and 'bar' have the same IDs they do not
     // clash because this call to @set_control_task_table will
     // decouple control tasks from data and local tasks. Control
     // tasks now have their own separate task table.
     @set_control_task_table(.{.instructions = 8, .stride = 4});
   }

Semantics
^^^^^^^^^

The ``@set_control_task_table`` builtin will decouple control tasks
from data and local tasks by creating a separate task table that is
dedicated to control tasks.

The builtin can only be called at most once during the evaluation of a
top-level comptime block.

It can have an optional argument that must be a comptime-known struct
with two optional fields: ``instructions`` and ``stride``.

If ``@set_control_task_table`` is called without an argument then the
default values for ``instructions`` and ``stride`` will be used (see
below).

The ``instructions`` field can be used to specify the number of instructions
for each entry point in the new control task table. The number of instructions
must be a comptime-known integer value within the valid set of options which are
``2``, ``4`` and ``8``. The default value is ``4``.

The ``stride`` field requires a comptime-known integer value that represents the
stride - in number of entry points - per input queue's local control table index
(see :ref:`language-builtins-initialize-queue`). Its value should be in the
range ``[1, 7]`` and the default value is ``1``.

.. _language-builtins-wse3-get-ut-id:

@get_ut_id
----------

Create a value of type ``ut_id`` from the provided integer identifier.

Syntax
^^^^^^

.. code-block:: csl

   @get_ut_id(id);

Where:

* ``id`` is a comptime-known expression of any unsigned integer type,
  or a runtime expression of type ``u16``.

Semantics
^^^^^^^^^

If ``id`` is comptime-known, the builtin will only accept integers
in the target architecture's valid range for microthread IDs.

If ``id`` is not comptime-known, its type must be ``u16``.
In this case no runtime checks are performed to ensure that ``id`` is
within the range of valid microthread IDs.