Lines Matching full:function
8 ``std::function``, but doesn't allocate, and uses several tricks to prevent
17 ``pw_function`` defines the :cpp:type:`pw::Function` class. A ``Function`` is a
28 // Construct a Function object from a function pointer.
29 pw::Function<int(int, int)> add_function(Add);
31 // Invoke the function object.
35 // Construct a function from a lambda.
36 pw::Function<int(int)> negate([](int value) { return -value; });
39 Functions are nullable. Invoking a null function triggers a runtime assert.
43 // A function initialized without a callable is implicitly null.
44 pw::Function<void()> null_function;
47 pw::Function<void()> explicit_null_function(nullptr);
49 pw::Function<void()> function([]() {}); // Valid (non-null) function.
50 function = nullptr; // Set to null, clearing the stored callable.
53 if (function != nullptr) {
54 function();
57 :cpp:type:`pw::Function`'s default constructor is ``constexpr``, so
65 // Default construction of a pw::Function is constexpr.
68 pw::Function<void(int)> my_function;
71 // pw::Function and classes that use it may be constant initialized.
76 By default, a ``Function`` stores its callable inline within the object. The
78 through the build system. The size of a ``Function`` object is equivalent to its
81 The :cpp:type:`pw::InlineFunction` alias is similar to :cpp:type:`pw::Function`,
83 :cpp:type:`pw::Function`, :cpp:type:`pw::InlineFunction` will fail to compile if
86 Attempting to construct a function from a callable larger than its inline size
92 callable objects, including function pointers, simple non-capturing and
97 // The lambda is moved into the function's internal storage.
98 pw::Function<int(int, int)> subtract([](int a, int b) { return a - b; });
110 // Compiler error: sizeof(MyCallable) exceeds function's inline storage size.
111 pw::Function<int(int)> function((MyCallable()));
115 When ``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` is enabled, a ``Function``
122 from `:cpp:type:`pw::InlineFunction` to a regular :cpp:type:`pw::Function`
131 .. doxygentypedef:: pw::Function
136 ``pw::Function`` as a function parameter
138 When implementing an API which takes a callback, a ``Function`` can be used in
139 place of a function pointer or equivalent callable.
146 // After. Note that it is possible to have parameter names within the function
148 void DoTheThing(int arg, const pw::Function<void(int result)>& callback);
150 :cpp:type:`pw::Function` is movable, but not copyable, so APIs must accept
151 :cpp:type:`pw::Function` objects either by const reference (``const
152 pw::Function<void()>&``) or rvalue reference (``const pw::Function<void()>&&``).
153 If the :cpp:type:`pw::Function` simply needs to be called, it should be passed
154 by const reference. If the :cpp:type:`pw::Function` needs to be stored, it
156 :cpp:type:`pw::Function` variable as appropriate.
160 // This function calls a pw::Function but doesn't store it, so it takes a
162 void CallTheCallback(const pw::Function<void(int)>& callback) {
166 // This function move-assigns a pw::Function to another variable, so it takes
168 void StoreTheCallback(pw::Function<void(int)>&& callback) {
172 .. admonition:: Rules of thumb for passing a :cpp:type:`pw::Function` to a function
176 This results in unnecessary :cpp:type:`pw::Function` instances and move
178 * **Pass by const reference** (``const pw::Function&``): When the
179 :cpp:type:`pw::Function` is only invoked.
181 When a :cpp:type:`pw::Function` is called or inspected, but not moved, take
183 * **Pass by rvalue reference** (``pw::Function&&``): When the
184 :cpp:type:`pw::Function` is moved.
186 When the function takes ownership of the :cpp:type:`pw::Function` object,
187 always use an rvalue reference (``pw::Function<void()>&&``) instead of a
188 mutable lvalue reference (``pw::Function<void()>&``). An rvalue reference
190 :cpp:type:`pw::Function` variable, which makes the transfer of ownership
193 * **Pass by non-const reference** (``pw::Function&``): Rarely, when modifying
197 :cpp:type:`pw::Function` variable. Use an rvalue reference instead if the
198 :cpp:type:`pw::Function` is moved into another variable.
200 Calling functions that use ``pw::Function``
202 A :cpp:type:`pw::Function` can be implicitly constructed from any callback
203 object. When calling an API that takes a :cpp:type:`pw::Function`, simply pass
205 :cpp:type:`pw::Function` object.
209 // Implicitly creates a pw::Function from a capturing lambda and calls it.
212 // Implicitly creates a pw::Function from a capturing lambda and stores it.
215 When working with an existing :cpp:type:`pw::Function` variable, the variable
216 can be passed directly to functions that take a const reference. If the function
217 takes ownership of the :cpp:type:`pw::Function`, move the
218 :cpp:type:`pw::Function` variable at the call site.
222 // Accepts the pw::Function by const reference.
225 // Takes ownership of the pw::Function.
230 :cpp:type:`pw::Callback` is a specialization of :cpp:type:`pw::Function` that
232 function is destroyed. A :cpp:type:`pw::Callback` in the "already called" state
236 Invoking ``pw::Function`` from a C-style API
256 Function class
258 The following size report compares an API using a :cpp:type:`pw::Function` to a
259 traditional function pointer.
266 be used as a reference when sizing external buffers for ``Function`` objects.
273 :cpp:type:`pw::Function` is an alias of
274 `fit::function <https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/lib/fit/include/lib/fit/fun…
277 …cs.opensource.google/fuchsia/fuchsia/+/main:sdk/lib/fit/include/lib/fit/function.h;drc=f66f54fca0c…