Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update function objects section to the new format #648

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Update function objects section to the new format #648

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c8b0fe2
Update function objects section to the new format
Pennycook Oct 24, 2024
f4eb1a8
Satisfy reflow
Pennycook Oct 24, 2024
5ae4b13
Fix copy-paste error in transparent operators
Pennycook Oct 25, 2024
0308265
Define minimum/maximum return type using a ternary
Pennycook Oct 25, 2024
e3d879f
Align minimum/maximum description with min/max
Pennycook Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
325 changes: 228 additions & 97 deletions adoc/chapters/programming_interface.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch!

----
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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) + std::forward<U>(u));
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a motivation to have the std::forward in the non-evaluated context?
Actually a maniac programmer could define + with an l-reference to do division and a + with an r-reference to do a multiplication?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know the motivation, but this is the way that the return type is declared for the equivalent function objects in in ISO C+ (e.g., https://eel.is/c++draft/function.objects#arithmetic.operations.plus-2).

I think you're right, though -- if std::forward<T>(t) + std::forward<U>(u) is the statement that the operator will run, it's safer to include the std::forward in the decltype just in case somebody does something really weird.

----
a@ Returns the product of its arguments, equivalent to [code]#x * y#.

|====
// Strange formatting here because + requires pass, but pass breaks <T>/<U>.
_Returns_: [code]#std::forward<T>(t)# [code]#pass:[+]#
[code]#std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) * std::forward<U>(u));
----
a@ Returns the bitwise XOR of its arguments, equivalent to [code]#x ^ y#.

|====
_Returns_: [code]#std::forward<T>(t) * std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) & std::forward<U>(u));
----
a@ Returns the smaller value. Returns the first argument when the arguments
are equivalent.

|====
_Returns_: [code]#std::forward<T>(t) & std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) | std::forward<U>(u));
----

_Returns_: [code]#std::forward<T>(t) | std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) ^ std::forward<U>(u));
----

_Returns_: [code]#std::forward<T>(t) ^ std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) && std::forward<U>(u));
----

_Returns_: [code]#std::forward<T>(t) && std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) || std::forward<U>(u));
----

_Returns_: [code]#std::forward<T>(t) || std::forward<U>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<U>(u) < std::forward<T>(t) ? std::forward<U>(u) : std::forward<T>(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 <class T, class U> constexpr auto operator()(T&& t, U&& u) const
-> decltype(std::forward<T>(t) < std::forward<U>(u) ? std::forward<U>(u) : std::forward<T>(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
Expand Down
Loading