Skip to content

Commit 279afdf

Browse files
committed
Restructure motivation section
1 parent 0586488 commit 279afdf

File tree

1 file changed

+6
-10
lines changed

1 file changed

+6
-10
lines changed

docs/reference/api/platform/platform.md

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -57,21 +57,17 @@ The Callback class manages C/C++ function pointers so you don't have to. If you
5757
5858
#### Why should you use Callbacks?
5959
60-
Unfortunately, supporting all of the standard C++ function types is difficult.
60+
Supporting all of the standard C++ function types is difficult for an API developer. An API developer must consider state, C++ Function objects, const correctness and volatile correctness.
6161
62-
- State is important, so need to support either C-style function pointers with state, or C++ member function pointers.
62+
State is important, so an API developer must support either C-style function pointers with state, or C++ member function pointers. Stateless callbacks are just as common, but passing a stateless callback as a member function function requires writing a lot of boilerplate code and instantiating an empty class. Further, an API developer also must support a standard function pointer.
6363
64-
- Stateless callbacks are just as common, but passing a stateless callback as a member function function requires writing a lot of boilerplate code and instantiating an empty class. So we need to also support a standard function pointer.
64+
Another common design pattern is the function object, a class that overrides the function call operator. A user may pass function objects as C++ member function pointers and C++ requires a large set of overloads to support all of the standard function types. It is unreasonable to expect a new library author to add all of these overloads to every function that could take in a callback.
6565
66-
- Another design pattern you may see is the function object, a class that overrides the function call operator. We can expect the user to pass function objects as C++ member function pointers if needed.
66+
A useful C++ feature is compile time const-correctness checks, which increases API complexity when combined by callbacks with state. To allow a user to take full advantage of the const-correctness checks, a C++ API must support both the const and non-const versions of member function pointers.
6767
68-
- A useful C++ feature is the enforcement of const-correctness, but this becomes unfortunately complicated with the state associated with callbacks. A C++ API needs to support both the const and non-const versions of member function pointers.
68+
Another useful C++ feature is volatile-correctness. When volatile-correctness is necessary, we expect that the user hides volatile members inside of a non-volatile class.
6969
70-
- Another C++ feature is volatile-correctness in case the underlying state must be volatile, but if necessary we can probably expect the user to hide volatile members inside of a non-volatile class.
71-
72-
C++ requires a large set of overloads to support all of the standard function types. It is unreasonable to expect a new library author to add all of these overloads to every function that could take in a callback.
73-
74-
C++ provides the tools to delegate this problem to a single class. This class is the Callback class. The Callback class should be familiar to users of the std::function class that C++11 introduced but is available for older versions of C++.
70+
C++ provides the tools to delegate this complexity to a single class. This class is the Callback class. The Callback class should be familiar to users of the std::function class that C++11 introduced and is available for older versions of C++.
7571
7672
<h4 id="the-importance-of-state">The importance of state</h4>
7773

0 commit comments

Comments
 (0)