[SYCL][Doc] Add deduction restrictions

Signed-off-by: John Pennycook <[email protected]>

Author: Pennycook

sycl/doc/extensions/GroupAlgorithms/SYCL_INTEL_group_algorithms.asciidoc

@@ -185,6 +185,8 @@ It is undefined behavior for any of these functions to be invoked within a +para
 
 In this section, the meaning of "exclusive scan" and "inclusive scan" are as defined in Sections 29.8.7 and 29.8.8 of the {cpp}17 specification, respectively.
 
+The return types of the collective functions in {cpp}17 are not deduced from the return type of the specified binary operator, but from either the type of the input values or the type of the initialization value (if one is provided).  This is error-prone and can lead to unexpected behavior (e.g. specifying an initial value of `0` instead of `0.0f` for a floating-point reduction will cause the results to be accumulated in an integer).  To minimize the chances of encountering such errors, the collective functions in the group algorithms library place additional restrictions on type combinations that can be deduced.  Expert users can override these restrictions by specifying all template arguments explicitly.
+
 |===
 |Function|Description
 
@@ -198,44 +200,44 @@ In this section, the meaning of "exclusive scan" and "inclusive scan" are as def
 |Broadcast the value of _x_ from the work-item with the specified id to all work-items within the group. The value of _local_id_ must be the same for all work-items in the group, and its dimensionality must match the dimensionality of the group.
 
 |+template <typename Group, typename T, class BinaryOperation> T reduce(Group g, T x, BinaryOperation binary_op);+
-|Combine the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  _binary_op_ must be the same for all work-items in the group.
+|Combine the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  _binary_op_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(x, x)_ must return a value of type _T_.
 
 |+template <typename Group, typename V, typename T, class BinaryOperation> T reduce(Group g, V x, T init, BinaryOperation binary_op);+
-|Combine the values of _x_ from all work-items in the group using an initial value of _init_ and the operator _binary_op_, which must be one of the group algorithms library function objects. _binary_op_ must be the same for all work-items in the group.
+|Combine the values of _x_ from all work-items in the group using an initial value of _init_ and the operator _binary_op_, which must be one of the group algorithms library function objects. _binary_op_ must be the same for all work-items in the group.  If _T_ is deduced, _binary_op(init, x)_ must return a value of type _T_.
 
 |+template <typename Group, typename T, class BinaryOperation> T exclusive_scan(Group g, T x, BinaryOperation binary_op);+
-|Perform an exclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the exclusive scan of the first +i+ work-items in the group and the identity value of _binary_op_. For multi-dimensional groups, the order of work-items in the group is determined by their linear id. _binary_op_ must be the same for all work-items in the group.
+|Perform an exclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the exclusive scan of the first +i+ work-items in the group and the identity value of _binary_op_. For multi-dimensional groups, the order of work-items in the group is determined by their linear id. _binary_op_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(x, x)_ must return a value of type _T_.
 
 |+template <typename Group, typename V, typename T, class BinaryOperation> T exclusive_scan(Group g, V x, T init, BinaryOperation binary_op);+
-|Perform an exclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the exclusive scan of the first +i+ work items in the group and an initial value specified by _init_. For multi-dimensional groups, the order of work-items in the group is determined by their linear id. _init_ and _binary_op_ must be the same for all work-items in the group.
+|Perform an exclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the exclusive scan of the first +i+ work items in the group and an initial value specified by _init_. For multi-dimensional groups, the order of work-items in the group is determined by their linear id. _init_ and _binary_op_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(init, x)_ must return a value of type _T_.
 
 |+template <typename Group, typename T, class BinaryOperation> T inclusive_scan(Group g, T x, BinaryOperation binary_op);+
-|Perform an inclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the inclusive scan of the first +i+ work items in the group. For multi-dimensional groups, the order of work-items in the group is determined by their linear id.  _binary_op_ must be the same for all work-items in the group.
+|Perform an inclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the inclusive scan of the first +i+ work items in the group. For multi-dimensional groups, the order of work-items in the group is determined by their linear id.  _binary_op_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(x, x)_ must return a value of type _T_.
 
 |+template <typename Group, typename V, class BinaryOperation, typename T> T inclusive_scan(Group g, V x, BinaryOperation binary_op, T init);+
-|Perform an inclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the inclusive scan of the first +i+ work items in the group and an initial value specified by _init_. For multi-dimensional groups, the order of work-items in the group is determined by their linear id.  _binary_op_ and _init_ must be the same for all work-items in the group.
+|Perform an inclusive scan over the values of _x_ from all work-items in the group using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value returned on work-item +i+ is the inclusive scan of the first +i+ work items in the group and an initial value specified by _init_. For multi-dimensional groups, the order of work-items in the group is determined by their linear id.  _binary_op_ and _init_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(init, x)_ must return a value of type _T_.
 |===
 
 |===
 |Function|Description
 
 |+template <typename Group, typename Ptr, class BinaryOperation> Ptr::element_type reduce(Group g, Ptr first, Ptr last, BinaryOperation binary_op);+
-|Combine the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  _first_, _last_ and _binary_op_ must be the same for all work-items in the group.
+|Combine the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  _first_, _last_ and _binary_op_ must be the same for all work-items in the group. If _Ptr_ is deduced, _binary_op(*first, *first)_ must return a value of type _Ptr::element_type_.
 
 |+template <typename Group, typename Ptr, typename T, class BinaryOperation> T reduce(Group g, Ptr first, Ptr last, T init, BinaryOperation binary_op);+
-|Combine the values in the range [_first_, _last_) using an initial value of _init_ and the operator _binary_op_, which must be one of the group algorithms library function objects.  _first_, _last_, _init__ and _binary_op_ must be the same for all work-items in the group.
+|Combine the values in the range [_first_, _last_) using an initial value of _init_ and the operator _binary_op_, which must be one of the group algorithms library function objects.  _first_, _last_, _init__ and _binary_op_ must be the same for all work-items in the group.  If _T_ is deduced, _binary_op(init, *first)_ must return a value of type _T_.
 
 |+template <typename Group, typename InPtr, typename OutPtr, class BinaryOperation> OutPtr exclusive_scan(Group g, InPtr first, InPtr last, OutPtr result, BinaryOperation binary_op);+
-|Perform an exclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the exclusive scan of the first +i+ values in the range and the identity value of _binary_op_.  Returns a pointer to the end of the output range.  _first_, _last_, _result_ and _binary_op_ must be the same for all work-items in the group.
+|Perform an exclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the exclusive scan of the first +i+ values in the range and the identity value of _binary_op_.  Returns a pointer to the end of the output range.  _first_, _last_, _result_ and _binary_op_ must be the same for all work-items in the group. If _Ptr_ is deduced, _binary_op(*first, *first)_ must return a value of type _Ptr::element_type_.
 
 |+template <typename Group, typename InPtr, typename OutPtr, typename T, class BinaryOperation> OutPtr exclusive_scan(Group g, InPtr first, InPtr last, OutPtr result, T init, BinaryOperation binary_op);+
-|Perform an exclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the exclusive scan of the first +i+ values in the range and an initial value specified by _init_.  Returns a pointer to the end of the output range. _first_, _last_, _result_, _init_ and _binary_op_ must be the same for all work-items in the group.
+|Perform an exclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the exclusive scan of the first +i+ values in the range and an initial value specified by _init_.  Returns a pointer to the end of the output range. _first_, _last_, _result_, _init_ and _binary_op_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(init, *first)_ must return a value of type _T_.
 
 |+template <typename Group, typename InPtr, typename OutPtr, class BinaryOperation> OutPtr inclusive_scan(Group g, InPtr first, InPtr last, OutPtr result, BinaryOperation binary_op);+
-|Perform an inclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the inclusive scan of the first +i+ values in the range. Returns a pointer to the end of the output range. _first_, _last_, _result_ and _binary_op_ must be the same for all work-items in the group.
+|Perform an inclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the inclusive scan of the first +i+ values in the range. Returns a pointer to the end of the output range. _first_, _last_, _result_ and _binary_op_ must be the same for all work-items in the group. If _Ptr_ is deduced, _binary_op(*first, *first)_ must return a value of type _Ptr::element_type_.
 
 |+template <typename Group, typename InPtr, typename OutPtr, class BinaryOperation, typename T> OutrPtr inclusive_scan(Group g, InPtr first, InPtr last, OutPtr result, BinaryOperation binary_op, T init);+
-|Perform an inclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the inclusive scan of the first +i+ values in the range and an initial value specified by _init_. Returns a pointer to the end of the output range. _first_, _last_, _result_, _binary_op_ and _init_ must be the same for all work-items in the group.
+|Perform an inclusive scan over the values in the range [_first_, _last_) using the operator _binary_op_, which must be one of the group algorithms library function objects.  The value written to +result + i+ is the inclusive scan of the first +i+ values in the range and an initial value specified by _init_. Returns a pointer to the end of the output range. _first_, _last_, _result_, _binary_op_ and _init_ must be the same for all work-items in the group. If _T_ is deduced, _binary_op(init, *first)_ must return a value of type _T_.
 |===
 
 == Issues