legate::TaskSignature#

class TaskSignature#

A helper class for specifying a task’s call signature.

This class is used to statically declare a task’s expected signature. For example:

legate::TaskSignature{}  // The task expects exactly 2 inputs...
  .inputs(2)
  // But may take at least 3 and no more than 5 outputs...
  .outputs(3, 5)
  // While taking an unbounded number of scalars (but must have at least 1)
  .scalars(1, legate::TaskSignature::UNBOUNDED)
  // With the following constraints imposed on the arguments
  .constraints(
    {{// Align the first input with the first output
      legate::align(legate::proxy::inputs[0], legate::proxy::outputs[0]),
      // Broadcast ALL inputs
      legate::broadcast(legate::proxy::inputs),
      // All arguments (including axes) of constraints are supported
      legate::scale({1, 2, 3}, legate::proxy::outputs[1], legate::proxy::inputs[1])}});

A tasks signature describes how many input, output, scalar, or reduction arguments they take, as well as any constraints that are to be applied to the task. If a task predeclares its signature in this manner, the runtime will be able to perform a number of optimizations and sanity-checks for the user, including (but not limited to):

Checking the number of arguments matches the expected signature (and raising exceptions if not).
Automatically applying constraints on task arguments.
Improved scheduling of tasks.

Note

While it is highly recommended that user statically declare their tasks’ signatures, the user is no longer allowed to deviate from the signature at runtime. For example, tasks that predeclare their constraints are not allowed to add additional constraints during task launch.

Public Functions

TaskSignature()#: Default-construct an empty TaskSignature.

TaskSignature &inputs(std::uint32_t n) noexcept#

Set the number of input arguments taken by the task.

If n is UNBOUNDED, it signifies that the task takes a variable (or possibly unknown) number of input arguments. Otherwise, this call signifies that a task takes exactly n input arguments, no more, no less.

See also

inputs(std::uint32_t, std::uint32_t).

Parameters:: n – The argument specification.
Returns:: A reference to this.

TaskSignature &inputs( std::uint32_t low_bound, std::uint32_t upper_bound )#

Set the number of input arguments taken by the task.

This call signifies that a task takes at least low_bound but no more than upper_bound number of input arguments. If upper_bound is UNBOUNDED, then the task takes at least low_bound number of arguments, but can take an unlimited number of arguments past that.

If given, upper_bound must be strictly greater than low_bound.

See also

inputs(std::uint32_t).

Parameters:

low_bound – The lower bound on the number of input arguments.
upper_bound – The upper bound on the number of input arguments.

Throws:

std::out_of_range – If upper_bound <= low_bound.

Returns:

A reference to this.

TaskSignature &outputs(std::uint32_t n) noexcept#

Set the number of output arguments taken by the task.

If n is UNBOUNDED, it signifies that the task takes a variable (or possibly unknown) number of output arguments. Otherwise, this call signifies that a task takes exactly n output arguments, no more, no less.

Parameters:: n – The argument specification.
Returns:: A reference to this.

TaskSignature &outputs( std::uint32_t low_bound, std::uint32_t upper_bound )#

Set the number of output arguments taken by the task.

This call signifies that a task takes at least low_bound but no more than upper_bound number of output arguments. If upper_bound is UNBOUNDED, then the task takes at least low_bound number of arguments, but can take an unlimited number of arguments past that.

If given, upper_bound must be strictly greater than low_bound.

See also

outputs(std::uint32_t).

Parameters:

low_bound – The lower bound on the number of output arguments.
upper_bound – The upper bound on the number of output arguments.

Throws:

std::out_of_range – If upper_bound <= low_bound.

Returns:

A reference to this.

TaskSignature &scalars(std::uint32_t n) noexcept#

Set the number of scalar arguments taken by the task.

If n is UNBOUNDED, it signifies that the task takes a variable (or possibly unknown) number of scalar arguments. Otherwise, this call signifies that a task takes exactly n scalar arguments, no more, no less.

Parameters:: n – The argument specification.
Returns:: A reference to this.

TaskSignature &scalars( std::uint32_t low_bound, std::uint32_t upper_bound )#

Set the number of scalar arguments taken by the task.

This call signifies that a task takes at least low_bound but no more than upper_bound number of scalar arguments. If upper_bound is UNBOUNDED, then the task takes at least low_bound number of arguments, but can take an unlimited number of arguments past that.

If given, upper_bound must be strictly greater than low_bound.

See also

scalars(std::uint32_t).

Parameters:

low_bound – The lower bound on the number of scalar arguments.
upper_bound – The upper bound on the number of scalar arguments.

Throws:

std::out_of_range – If upper_bound <= low_bound.

Returns:

A reference to this.

TaskSignature &redops(std::uint32_t n) noexcept#

Set the number of redop arguments taken by the task.

If n is UNBOUNDED, it signifies that the task takes a variable (or possibly unknown) number of redop arguments. Otherwise, this call signifies that a task takes exactly n redop arguments, no more, no less.

See also

redops(std::uint32_t, std::uint32_t).

Parameters:: n – The argument specification.
Returns:: A reference to this.

TaskSignature &redops( std::uint32_t low_bound, std::uint32_t upper_bound )#

Set the number of redop arguments taken by the task.

This call signifies that a task takes at least low_bound but no more than upper_bound number of redop arguments. If upper_bound is UNBOUNDED, then the task takes at least low_bound number of arguments, but can take an unlimited number of arguments past that.

If given, upper_bound must be strictly greater than low_bound.

See also

redops(std::uint32_t).

Parameters:

low_bound – The lower bound on the number of redop arguments.
upper_bound – The upper bound on the number of redop arguments.

Throws:

std::out_of_range – If upper_bound <= low_bound.

Returns:

A reference to this.

TaskSignature &constraints( std::optional<Span<const ProxyConstraint>> constraints )#

Set the constraints imposed on task arguments.

Passing std::nullopt vs passing an empty range has different meanings:

If std::nullopt is passed, this is taken to mean that an unknown number of dynamic constraints (of that type) may be imposed on the task during launch.
Passing an empty range signifies that exactly 0 constraints of the given type must be imposed on the task during launch.

If any constraints are imposed via the use of this API (including empty ranges), tasks are no longer allowed to add constraints dynamically during task construction. AutoTask::add_constraint() will raise an exception in this case.

Parameters:: constraints – The constraints, or std::nullopt if none are imposed.
Returns:: A reference to this.

Public Static Attributes

static auto UNBOUNDED = std::numeric_limits<std::uint32_t>::max()#

A value indicating that a particular option has “unbounded” (or unknown) number of possibilities.

This is commonly used for e.g. inputs(), outputs(), scalars(), or redops() when a task takes an unknown number of arguments, or when the upper limit on the number of arguments is unknown.