diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 2332823df..79216b301 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -21277,142 +21277,273 @@ requirements for both host and device. SYCL provides a number of function objects in the [code]#sycl# namespace on host and device. -All function objects obey {cpp} conversion and promotion rules. -Each function object is additionally specialized for [code]#void# as a -_transparent_ function object that deduces its parameter types and return type. -[source,,linenums] +==== [code]#plus# class template + +[source,role=synopsis] ---- -include::{header_dir}/functional.h[lines=4..-1] +include::{header_dir}/functional/plus.h[lines=4..-1] ---- -[[table.function.objects.plus]] -.Member functions for the [code]#plus# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:plus-call-operator] ---- -T operator()(const T& x, const T& y) const +T operator()(const T& x, const T& y) const; ---- - a@ Returns the sum of its arguments, equivalent to [code]#pass:[x + y]#. -|==== +_Returns_: [code]#pass:[x + y]#. -[[table.function.objects.multiplies]] -.Member functions for the [code]#multiplies# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:plus-transparent-call-operator] ---- -T operator()(const T& x, const T& y) const +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) + std::forward(u)); ---- - a@ Returns the product of its arguments, equivalent to [code]#x * y#. -|==== +// Strange formatting here because + requires pass, but pass breaks /. +_Returns_: [code]#std::forward(t)# [code]#pass:[+]# +[code]#std::forward(u)#. -[[table.function.objects.bit-and]] -.Member functions for the [code]#bit_and# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +==== [code]#multiplies# class template + +[source,role=synopsis] ---- -T operator()(const T& x, const T& y) const +include::{header_dir}/functional/multiplies.h[lines=4..-1] ---- - a@ Returns the bitwise AND of its arguments, equivalent to [code]#x & y#. -|==== +''' -[[table.function.objects.bit-or]] -.Member functions for the [code]#bit_or# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +.[apititle]#call operator# +[source,role=synopsis,id=api:multiplies-call-operator] ---- -T operator()(const T& x, const T& y) const +T operator()(const T& x, const T& y) const; ---- - a@ Returns the bitwise OR of its arguments, equivalent to [code]#x | y#. -|==== +_Returns_: [code]#x * y#. -[[table.function.objects.bit-xor]] -.Member functions for the [code]#bit_xor# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:multiplies-transparent-call-operator] ---- -T operator()(const T& x, const T& y) const +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) * std::forward(u)); ---- - a@ Returns the bitwise XOR of its arguments, equivalent to [code]#x ^ y#. -|==== +_Returns_: [code]#std::forward(t) * std::forward(u)#. -[[table.function.objects.logical-and]] -.Member functions for the [code]#logical_and# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +==== [code]#bit_and# class template + +[source,role=synopsis] ---- -T operator()(const T& x, const T& y) const +include::{header_dir}/functional/bit_and.h[lines=4..-1] ---- - a@ Returns the logical AND of its arguments, equivalent to [code]#x && y#. -|==== +''' -[[table.function.objects.logical-or]] -.Member functions for the [code]#logical_or# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +.[apititle]#call operator# +[source,role=synopsis,id=api:bit_and-call-operator] ---- -T operator()(const T& x, const T& y) const +T operator()(const T& x, const T& y) const; ---- - a@ Returns the logical OR of its arguments, equivalent to [code]#x || y#. -|==== +_Returns_: [code]#x & y#. -[[table.function.objects.minimum]] -.Member functions for the [code]#minimum# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:bit_and-transparent-call-operator] ---- -T operator()(const T& x, const T& y) const +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) & std::forward(u)); ---- - a@ Returns the smaller value. Returns the first argument when the arguments - are equivalent. -|==== +_Returns_: [code]#std::forward(t) & std::forward(u)#. -[[table.function.objects.maximum]] -.Member functions for the [code]#maximum# function object -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +==== [code]#bit_or# class template + +[source,role=synopsis] ---- -T operator()(const T& x, const T& y) const +include::{header_dir}/functional/bit_or.h[lines=4..-1] ---- - a@ Returns the larger value. Returns the first argument when the arguments - are equivalent. -|==== +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:bit_or-call-operator] +---- +T operator()(const T& x, const T& y) const; +---- + +_Returns_: [code]#x | y#. + +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:bit_or-transparent-call-operator] +---- +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) | std::forward(u)); +---- + +_Returns_: [code]#std::forward(t) | std::forward(u)#. + +==== [code]#bit_xor# class template + +[source,role=synopsis] +---- +include::{header_dir}/functional/bit_xor.h[lines=4..-1] +---- + +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:bit_xor-call-operator] +---- +T operator()(const T& x, const T& y) const; +---- + +_Returns_: [code]#x ^ y#. + +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:bit_xor-transparent-call-operator] +---- +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) ^ std::forward(u)); +---- + +_Returns_: [code]#std::forward(t) ^ std::forward(u)#. + +==== [code]#logical_and# class template + +[source,role=synopsis] +---- +include::{header_dir}/functional/logical_and.h[lines=4..-1] +---- + +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:logical_and-call-operator] +---- +bool operator()(const T& x, const T& y) const; +---- + +_Returns_: [code]#x && y#. + +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:logical_and-transparent-call-operator] +---- +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) && std::forward(u)); +---- + +_Returns_: [code]#std::forward(t) && std::forward(u)#. + +==== [code]#logical_or# class template + +[source,role=synopsis] +---- +include::{header_dir}/functional/logical_or.h[lines=4..-1] +---- + +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:logical_or-call-operator] +---- +bool operator()(const T& x, const T& y) const; +---- + +_Returns_: [code]#x || y#. + +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:logical_or-transparent-call-operator] +---- +template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) || std::forward(u)); +---- + +_Returns_: [code]#std::forward(t) || std::forward(u)#. + +==== [code]#minimum# class template + +[source,role=synopsis] +---- +include::{header_dir}/functional/minimum.h[lines=4..-1] +---- + +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:minimum-call-operator] +---- +T operator()(const T& x, const T& y) const; +---- + +_Preconditions_: [code]#T# meets the Cpp17LessThanComparable requirements. + +_Returns_: The smaller value. +Returns the first value when the arguments are equivalent. + +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:minimum-transparent-call-operator] +---- +template constexpr auto operator()(T&& t, U&& u) const +-> decltype(std::forward(u) < std::forward(t) ? std::forward(u) : std::forward(t)); +---- + +_Preconditions_: [code]#T# meets the Cpp17LessThanComparable requirements. + +_Returns_: The smaller value. +Returns the first value when the arguments are equivalent. + +==== [code]#maximum# class template + +[source,role=synopsis] +---- +include::{header_dir}/functional/maximum.h[lines=4..-1] +---- + +''' + +.[apititle]#call operator# +[source,role=synopsis,id=api:maximum-call-operator] +---- +T operator()(const T& x, const T& y) const; +---- + +_Preconditions_: [code]#T# meets the Cpp17LessThanComparable requirements. + +_Returns_: The larger value. +Returns the first value when the arguments are equivalent. + +''' + +.[apititle]#transparent call operator# +[source,role=synopsis,id=api:maximum-transparent-call-operator] +---- +template constexpr auto operator()(T&& t, U&& u) const +-> decltype(std::forward(t) < std::forward(u) ? std::forward(u) : std::forward(t)); +---- + +_Preconditions_: [code]#T# meets the Cpp17LessThanComparable requirements. + +_Returns_: The larger value. +Returns the first value when the arguments are equivalent. + [[sec:group-functions]] === Group functions diff --git a/adoc/headers/functional.h b/adoc/headers/functional.h deleted file mode 100644 index e9a00cff1..000000000 --- a/adoc/headers/functional.h +++ /dev/null @@ -1,42 +0,0 @@ -// Copyright (c) 2011-2024 The Khronos Group, Inc. -// SPDX-License-Identifier: MIT - -namespace sycl { - -template struct plus { - T operator()(const T& x, const T& y) const; -}; - -template struct multiplies { - T operator()(const T& x, const T& y) const; -}; - -template struct bit_and { - T operator()(const T& x, const T& y) const; -}; - -template struct bit_or { - T operator()(const T& x, const T& y) const; -}; - -template struct bit_xor { - T operator()(const T& x, const T& y) const; -}; - -template struct logical_and { - T operator()(const T& x, const T& y) const; -}; - -template struct logical_or { - T operator()(const T& x, const T& y) const; -}; - -template struct minimum { - T operator()(const T& x, const T& y) const; -}; - -template struct maximum { - T operator()(const T& x, const T& y) const; -}; - -} // namespace sycl diff --git a/adoc/headers/functional/bit_and.h b/adoc/headers/functional/bit_and.h new file mode 100644 index 000000000..05c91cf78 --- /dev/null +++ b/adoc/headers/functional/bit_and.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct bit_and { + T operator()(const T& x, const T& y) const; +}; + +template <> struct bit_and { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) & std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/bit_or.h b/adoc/headers/functional/bit_or.h new file mode 100644 index 000000000..356f1cf8b --- /dev/null +++ b/adoc/headers/functional/bit_or.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct bit_or { + T operator()(const T& x, const T& y) const; +}; + +template <> struct bit_or { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) | std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/bit_xor.h b/adoc/headers/functional/bit_xor.h new file mode 100644 index 000000000..3b10513f0 --- /dev/null +++ b/adoc/headers/functional/bit_xor.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct bit_xor { + T operator()(const T& x, const T& y) const; +}; + +template <> struct bit_xor { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) ^ std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/logical_and.h b/adoc/headers/functional/logical_and.h new file mode 100644 index 000000000..e081dc263 --- /dev/null +++ b/adoc/headers/functional/logical_and.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct logical_and { + bool operator()(const T& x, const T& y) const; +}; + +template <> struct logical_and { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) && std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/logical_or.h b/adoc/headers/functional/logical_or.h new file mode 100644 index 000000000..beaf8516d --- /dev/null +++ b/adoc/headers/functional/logical_or.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct logical_or { + bool operator()(const T& x, const T& y) const; +}; + +template <> struct logical_or { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) || std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/maximum.h b/adoc/headers/functional/maximum.h new file mode 100644 index 000000000..65a565454 --- /dev/null +++ b/adoc/headers/functional/maximum.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct maximum { + T operator()(const T& x, const T& y) const; +}; + +template <> struct maximum { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) < std::forward(u) ? std::forward(u) : std::forward(t)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/minimum.h b/adoc/headers/functional/minimum.h new file mode 100644 index 000000000..d71b782f7 --- /dev/null +++ b/adoc/headers/functional/minimum.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct minimum { + T operator()(const T& x, const T& y) const; +}; + +template <> struct minimum { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(u) < std::forward(t) ? std::forward(u) : std::forward(t)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/multiplies.h b/adoc/headers/functional/multiplies.h new file mode 100644 index 000000000..741ebb16e --- /dev/null +++ b/adoc/headers/functional/multiplies.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct multiplies { + T operator()(const T& x, const T& y) const; +}; + +template <> struct multiplies { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) * std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl diff --git a/adoc/headers/functional/plus.h b/adoc/headers/functional/plus.h new file mode 100644 index 000000000..70a1f637f --- /dev/null +++ b/adoc/headers/functional/plus.h @@ -0,0 +1,17 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: MIT + +namespace sycl { + +template struct plus { + T operator()(const T& x, const T& y) const; +}; + +template <> struct plus { + template constexpr auto operator()(T&& t, U&& u) const + -> decltype(std::forward(t) + std::forward(u)); + + using is_transparent = /* unspecified */; +}; + +} // namespace sycl