stl-utilities#

group Utilities

Functions

template<typename Function> unspecified elementwise(Function &&fn)#

A functional adaptor that, given a callable object fn, returns another callable object g that applies fn element-wise to its arguments.

The arguments to g must be mdspan objects or models of the logical_store_like concept. The shapes of the input arguments must all match. The element-wise application of f is performed lazily; i.e., the result is not computed until the elements of the result are accessed.

Example:

// Perform element-wise addition of the rows of two logical stores,
// assigning the result element-wise into the rows of the first.
stl::logical_store<int, 2> store1 = {
  {1, 2, 3, 4},  // row 0
  {2, 3, 4, 5},  // row 1
  {3, 4, 5, 6}   // row 2
};
stl::logical_store<int, 2> store2 = {
  {10, 20, 30, 40},  // row 0
  {20, 30, 40, 50},  // row 1
  {30, 40, 50, 60}   // row 2
};
stl::transform(stl::rows_of(store1),
               stl::rows_of(store2),
               stl::rows_of(store1),
               stl::elementwise(std::plus<>{}));

// store1 now contains:
// [[11 22 33 44]   // row 0
//  [22 33 44 55]   // row 1
//  [33 44 55 66]]  // row 2

Note

The Legate.STL algorithms recognize the return type of \(\mathtt{elementwise(fn)(}A^1,A^2\cdots,A^n\mathtt{)}\) such that assigning its result to an mdspan object will perform an element-wise assignment. The element-wise assignment is done with thrust::copy and will be accelerated if CUDA support is enabled.

Parameters:: fn – The callable object to apply element-wise.
Returns:: A callable object \(\mathtt{g}\) such that, given multi-dimensional arguments \(A^1,A^2\cdots,A^n\), the expression \(\mathtt{g(}A^1,A^2\cdots,A^n\mathtt{)}\) returns a multi-dimensional view \(\mathtt{V}\) where \(\mathtt{V}_{i,j,\ldots}\) is the result of calling \(\mathtt{fn(}{A^1}_{i,j,\ldots}, {A^2}_{i,j,\ldots}, \cdots, {A^n}_{i,j,\ldots}\mathtt{)}\).

template<LaunchParam... Params> void launch_task(Params... params)#

A function that launches a task with the given inputs, outputs, scalars, and constraints.

Launch parameter arguments can be one of the following in any order:

legate::experimental::stl::inputs - specifies the input stores for the task
- Example:
```
inputs(store1, store2, store3)
```
legate::experimental::stl::outputs - specifies the output stores for the task
- Example:
```
outputs(store1, store2, store3)
```
legate::experimental::stl::scalars - specifies the scalar arguments for the task
- Example:
```
scalars(42, 3.14f)
```
legate::experimental::stl::function - specifies the function to be applied iteratively to the inputs.
- The function will take as arguments the current elements of the input stores, in order, followed by the current elements of the output stores. The elements of a stl::logical_store are lvalue references to the elements of the physical store it represents. The elements of a view such as stl::rows_of(store) are mdspans denoting the rows of store.
- The function must be bitwise copyable.
- Only one of function or reduction can be specified in a call to launch_task
- Example:
```
function([](const auto& in, auto& out) { out = in * in; })
```
legate::experimental::stl::reduction - specifies the reduction store and the reduction function to be applied to the inputs.
- The function must be bitwise copyable.
- The reduction function must take as mdspans referring to parts of the input stores.
- The reduction store can be a logical_store or some view of a store, such as rows_of(store). When operating on a view, the arguments to the reduction function will be the elements of the view. For example, if the reduction store is rows_of(store), the arguments passed to the reduction function will be mdspans denoting rows of store.
- Only one of function or reduction can be specified in a call to launch_task
- Example:
```
stl::reduction(stl::rows_of(store), stl::elementwise(std::plus{}))
```
legate::experimental::stl::constraints - specifies the constraints for the task.
- A constraint is a callable that takes an legate::AutoTask& and the input, output, and reduction stores as arguments. Its function signature must be:
```
void(legate::AutoTask&,                // the task to add the constraints to
     const std::vector<LogicalStore>&, // the input stores
     const std::vector<LogicalStore>&, // the output stores
     const LogicalStore&)              // the reduction store
```
- Legate.STL provides one constraint generator, legate::experimental::stl::align, for specifying the alignment constraints for the task. It can be used many different ways:
  - align(inputs[0], inputs[1]) - aligns the first input with the second input
  - align(inputs[0], outputs[0]) - aligns the first input with the first output
  - align(outputs[0], inputs) - aligns the first output with all the inputs
  - align(outputs, inputs[1]) - aligns all the outputs with the second input
  - align(reduction, inputs[0]) - aligns the reduction store with the first input
  - align(reduction, inputs) - aligns the reduction store with all the input
  - align(inputs) - aligns all the inputs with each other
  - align(outputs) - aligns all the outputs with each other

Example

The following use of launch_task is equivalent to stl::transform(input, output op):

stl::launch_task(stl::function(detail::UnaryTransform{std::move(op)}),
                 stl::inputs(std::forward<InputRange>(input)),
                 stl::outputs(std::forward<OutputRange>(output)),
                 stl::constraints(stl::align(stl::inputs[0], stl::outputs[0])));

Variables

ResourceConfig LEGATE_STL_RESOURCE_CONFIG = {1024, 1024, 64, 0, 0}#

Configuration for the Legate STL resource.

This constant represents the configuration for the Legate STL resource. It specifies (in order):

the maximum number of tasks,
the maximum number of dynamic tasks,
the maximum number of reduction operations,
the maximum number of projections, and
the maximum number of shardings

that can be used in a program using Legate.STL.