Lines Matching full:function
10 wrapping callable objects that's similar to `std::function`_.
14 .. _std\:\:function: https://en.cppreference.com/w/cpp/utility/functional/function
18 #include "pw_function/function.h"
20 // pw::Function can be constructed from a function pointer...
22 pw::Function<int(int, int)> add(_a);
24 pw::Function<int(int)> square([](int num) { return num * num; });
27 // function is released and destroyed, along with any resources owned by
28 // that function.
34 add = nullptr; // pw::Function and pw::Callback are nullable
100 #include "pw_function/function.h"
110 Construct ``pw::Function`` from a function pointer
112 :cpp:type:`pw::Function` is a move-only callable wrapper constructable from any
114 implements the call operator; invoking a ``pw::Function`` object forwards to
121 // Construct a Function object from a function pointer.
122 pw::Function<int(int, int)> add_function(Add);
124 // Invoke the function object.
128 Construct ``pw::Function`` from a lambda
132 // Construct a function from a lambda.
133 pw::Function<int(int)> negate([](int value) { return -value; });
138 :cpp:type:`pw::Callback` is a specialization of :cpp:type:`pw::Function` that
140 function is released and destroyed, along with any resources owned by that
141 function. A :cpp:type:`pw::Callback` in the "already called" state
142 has the same state as a :cpp:type:`pw::Function` that has been assigned to
156 ``pw::Function`` and ``pw::Callback`` are nullable and can be compared to
157 ``nullptr``. Invoking a null function triggers a runtime assert.
161 // A function initialized without a callable is implicitly null.
162 pw::Function<void()> null_function;
165 pw::Function<void()> explicit_null_function(nullptr);
167 pw::Function<void()> function([]() {}); // Valid (non-null) function.
168 function = nullptr; // Set to null, clearing the stored callable.
171 if (function != nullptr) {
172 function();
177 The default constructor for :cpp:type:`pw::Function` is ``constexpr``, so
185 // Default construction of a pw::Function is constexpr.
188 pw::Function<void(int)> my_function;
191 // pw::Function and classes that use it may be constant initialized.
194 ``pw::Function`` as a function parameter
196 When implementing an API which uses callbacks, ``pw::Function`` can be used in
197 place of a function pointer or equivalent callable.
205 void DoTheThing(int arg, const pw::Function<void(int result)>& callback);
206 // Note the parameter name within the function signature template for clarity.
212 :cpp:type:`pw::Function` is movable, but not copyable, so APIs must accept
213 :cpp:type:`pw::Function` objects either by const reference (``const
214 pw::Function<void()>&``) or rvalue reference (``const pw::Function<void()>&&``).
215 If the :cpp:type:`pw::Function` simply needs to be called, it should be passed
216 by const reference. If the :cpp:type:`pw::Function` needs to be stored, it
218 :cpp:type:`pw::Function` variable as appropriate.
222 // This function calls a pw::Function but doesn't store it, so it takes a
224 void CallTheCallback(const pw::Function<void(int)>& callback) {
228 // This function move-assigns a pw::Function to another variable, so it takes
230 void StoreTheCallback(pw::Function<void(int)>&& callback) {
234 .. admonition:: Rules of thumb for passing a :cpp:type:`pw::Function` to a function
237 This results in unnecessary :cpp:type:`pw::Function` instances and move
240 * **Pass by const reference** (``const pw::Function&``): When the
241 :cpp:type:`pw::Function` is only invoked.
243 When a :cpp:type:`pw::Function` is called or inspected, but not moved, take
246 * **Pass by rvalue reference** (``pw::Function&&``): When the
247 :cpp:type:`pw::Function` is moved.
249 When the function takes ownership of the :cpp:type:`pw::Function` object,
250 always use an rvalue reference (``pw::Function<void()>&&``) instead of a
251 mutable lvalue reference (``pw::Function<void()>&``). An rvalue reference
253 :cpp:type:`pw::Function` variable, which makes the transfer of ownership
257 * **Pass by non-const reference** (``pw::Function&``): Rarely, when modifying
261 :cpp:type:`pw::Function` variable. Use an rvalue reference instead if the
262 :cpp:type:`pw::Function` is moved into another variable.
264 Calling functions that use ``pw::Function``
266 A :cpp:type:`pw::Function` can be implicitly constructed from any callback
267 object. When calling an API that takes a :cpp:type:`pw::Function`, simply pass
269 :cpp:type:`pw::Function` object.
273 // Implicitly creates a pw::Function from a capturing lambda and calls it.
276 // Implicitly creates a pw::Function from a capturing lambda and stores it.
279 When working with an existing :cpp:type:`pw::Function` variable, the variable
280 can be passed directly to functions that take a const reference. If the function
281 takes ownership of the :cpp:type:`pw::Function`, move the
282 :cpp:type:`pw::Function` variable at the call site.
286 // Accepts the pw::Function by const reference.
289 // Takes ownership of the pw::Function.
294 By default, ``pw::Function`` stores its callable inline within the object. The
298 :cpp:type:`pw::InlineFunction` is similar to ``pw::Function``,
300 ``pw::Function``, ``pw::InlineFunction`` will fail to compile if
303 Attempting to construct a function from a callable larger than its inline size
309 callable objects, including function pointers, simple non-capturing and
314 // The lambda is moved into the function's internal storage.
315 pw::Function<int(int, int)> subtract([](int a, int b) { return a - b; });
327 // Compiler error: sizeof(MyCallable) exceeds function's inline storage size.
328 pw::Function<int(int)> function((MyCallable()));
332 You can configure the inline allocation size of ``pw::Function`` and whether it
333 dynamically allocates, but it applies to all uses of ``pw::Function``.
335 As mentioned in :ref:`module-pw_function-design`, ``pw::Function`` is an alias
336 of Fuchsia's ``fit::function``. ``fit::function`` allows you to specify the
338 callable target doesn't inline. If you want to use a function class with
339 different attributes, you can interact with ``fit::function`` directly but note
343 When ``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` is enabled, a ``pw::Function``
356 :cpp:type:`pw::Function` will **ALWAYS** allocate memory.
358 Invoking ``pw::Function`` from a C-style API
364 :cpp:type:`pw::function::GetFunctionPointer()`.
372 ``pw::Function``
374 .. doxygentypedef:: pw::Function
392 ``pw::function::GetFunctionPointer()``
399 ``pw::function::GetFunctionPointerContextFirst()``
414 ``pw::Function`` is an alias of Fuchsia's ``fit::function_impl`` and
418 …clude/lib/fit/function.h <https://cs.opensource.google/pigweed/pigweed/+/main:third_party/fuchsia/…
419 * `fit::function <https://fuchsia.googlesource.com/fuchsia/+/HEAD/sdk/lib/fit/#fit_function>`_
423 Why ``pw::Function`` is not a literal
425 The default constructor for ``pw::Function`` is ``constexpr`` but
426 ``pw::Function`` is not a literal type. Instances can be declared ``constinit``
429 * ``pw::Function`` supports wrapping any callable type, and the wrapped type
431 * ``pw::Function`` stores inline callables in a bytes array, which is not
433 * ``pw::Function`` optionally uses dynamic allocation, which doesn't work in
440 Comparing ``pw::Function`` to a traditional function pointer
442 The following size report compares an API using a :cpp:type:`pw::Function` to a
443 traditional function pointer.
450 be used as a reference when sizing external buffers for ``pw::Function``