Lines Matching full:pw
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; });
26 // pw::Callback can only be invoked once. After the first call, the target
29 pw::Callback<void(void)> flip_table_once([](void) {
34 add = nullptr; // pw::Function and pw::Callback are nullable
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
122 pw::Function<int(int, int)> add_function(Add);
128 Construct ``pw::Function`` from a lambda
133 pw::Function<int(int)> negate([](int value) { return -value; });
136 Create single-use functions with ``pw::Callback``
138 :cpp:type:`pw::Callback` is a specialization of :cpp:type:`pw::Function` that
139 can only be called once. After a :cpp:type:`pw::Callback` is called, the target
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
147 pw::Callback<void(void)> flip_table_once([](void) {
156 ``pw::Function`` and ``pw::Callback`` are nullable and can be compared to
162 pw::Function<void()> null_function;
165 pw::Function<void()> explicit_null_function(nullptr);
167 pw::Function<void()> function([]() {}); // Valid (non-null) 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
205 void DoTheThing(int arg, const pw::Function<void(int result)>& callback);
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
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
315 pw::Function<int(int, int)> subtract([](int a, int b) { return a - b; });
328 pw::Function<int(int)> function((MyCallable()));
334 You can configure the inline allocation size of ``pw::Function`` and whether it
335 dynamically allocates, but it applies to all uses of ``pw::Function``.
337 As mentioned in :ref:`module-pw_function-design`, ``pw::Function`` is an alias
345 When ``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` is enabled, a ``pw::Function``
352 ``pw::InlineFunction`` can be used.
357 cast from :cpp:type:`pw::InlineFunction` to a regular
358 :cpp:type:`pw::Function` will **ALWAYS** allocate memory.
363 allocation. This is required for some modules that use ``pw::Function``,
369 Invoking ``pw::Function`` from a C-style API
375 :cpp:type:`pw::function::GetFunctionPointer()`.
383 ``pw::Function``
385 .. doxygentypedef:: pw::Function
387 ``pw::InlineFunction``
389 .. doxygentypedef:: pw::InlineFunction
391 ``pw::Callback``
393 .. doxygentypedef:: pw::Callback
395 ``pw::InlineCallback``
397 .. doxygentypedef:: pw::InlineCallback
399 ``pw::bind_member()``
401 .. doxygenfunction:: pw::bind_member
403 ``pw::function::GetFunctionPointer()``
410 ``pw::function::GetFunctionPointerContextFirst()``
415 ``pw::ScopeGuard``
417 .. doxygenclass:: pw::ScopeGuard
425 ``pw::Function`` is an alias of Fuchsia's ``fit::function_impl`` and
426 ``pw::Callback`` is an alias of Fuchsia's ``fit::callback_impl``. See the
434 Why ``pw::Function`` is not a literal
436 The default constructor for ``pw::Function`` is ``constexpr`` but
437 ``pw::Function`` is not a literal type. Instances can be declared ``constinit``
440 * ``pw::Function`` supports wrapping any callable type, and the wrapped type
442 * ``pw::Function`` stores inline callables in a bytes array, which is not
444 * ``pw::Function`` optionally uses dynamic allocation, which doesn't work in
451 Comparing ``pw::Function`` to a traditional function pointer
453 The following size report compares an API using a :cpp:type:`pw::Function` to a
461 be used as a reference when sizing external buffers for ``pw::Function``