diff --git a/sycl/doc/extensions/Reduction/Reduction.md b/sycl/doc/extensions/Reduction/Reduction.md index 7317d1167b932..37a6748142519 100644 --- a/sycl/doc/extensions/Reduction/Reduction.md +++ b/sycl/doc/extensions/Reduction/Reduction.md @@ -22,9 +22,21 @@ unspecified reduction(accessor& var, BinaryOperation combiner); template unspecified reduction(accessor& var, const T& identity, BinaryOperation combiner); + +template +unspecified reduction(T* var, BinaryOperation combiner); + +template +unspecified reduction(T* var, const T& identity, BinaryOperation combiner); + +template +unspecified reduction(span var, BinaryOperation combiner); + +template +unspecified reduction(span var, const T& identity, BinaryOperation combiner); ``` -The exact behavior of a reduction is specific to an implementation; the only interface exposed to the user is the pair of functions above, which construct an unspecified `reduction` object encapsulating the reduction variable, an optional operator identity and the reduction operator. For user-defined binary operations, an implementation should issue a compile-time warning if an identity is not specified and this is known to negatively impact performance (e.g. as a result of the implementation choosing a different reduction algorithm). For standard binary operations (e.g. `std::plus`) on arithmetic types, the implementation must determine the correct identity automatically in order to avoid performance penalties. +The exact behavior of a reduction is specific to an implementation; the only interface exposed to the user is the set of functions above, which construct an unspecified `reduction` object encapsulating the reduction variable, an optional operator identity and the reduction operator. For user-defined binary operations, an implementation should issue a compile-time warning if an identity is not specified and this is known to negatively impact performance (e.g. as a result of the implementation choosing a different reduction algorithm). For standard binary operations (e.g. `std::plus`) on arithmetic types, the implementation must determine the correct identity automatically in order to avoid performance penalties. The dimensionality of the `accessor` passed to the `reduction` function specifies the dimensionality of the reduction variable: a 0-dimensional `accessor` represents a scalar reduction, and any other dimensionality represents an array reduction. Specifying an array reduction of size N is functionally equivalent to specifying N independent scalar reductions. The access mode of the accessor determines whether the reduction variable's original value is included in the reduction (i.e. for `access::mode::read_write` it is included, and for `access::mode::discard_write` it is not). Multiple reductions aliasing the same output results in undefined behavior. @@ -33,22 +45,27 @@ The dimensionality of the `accessor` passed to the `reduction` function specifie # `reducer` Objects ```c++ -template +// Exposition only +template class reducer { // forbid reducer objects from being copied - reducer(const reducer&) = delete; - reducer& operator(const reducer&) = delete; + reducer(const reducer&) = delete; + reducer& operator(const reducer&) = delete; // combine partial result with reducer + // only available if Dimensions == 0 void combine(const T& partial); + // only available if Dimensions > 1 + unspecified &operator[](size_t index) const; + // get identity of the associated reduction (if known) T identity() const; }; // other operators should be made available for standard functors -template auto& operator+=(reducer>&, const T&); +template auto& operator+=(reducer,0>&, const T&); ``` The `reducer` class is not user-constructible, and can only be constructed by an implementation given a `reduction` object. The `combine` function uses the specified `BinaryOperation` to combine the `partial` result with the value held (or referenced) by an instance of `reducer`, and is the only way to update the reducer value for user-supplied combination functions. Other convenience operators should be defined for standard combination functions (e.g. `+=` for `std::plus`).