pw_function

Oveview

Embedded-friendly std::function: https://pigweed.dev/pw_function.

Classes
class	pw::ScopeGuard< Functor >

Macros
#define	PW_FUNCTION_INLINE_CALLABLE_SIZE   (sizeof(void*))
#define	PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION   0
#define	PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE   fit::default_callable_allocator

Typedefs
template<typename FunctionType >
using	pw::Function = fit::function_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE >
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize>
using	pw::InlineFunction = fit::inline_function< FunctionType, inline_target_size >
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>
using	pw::DynamicFunction = fit::function_impl< inline_target_size, false, FunctionType, Allocator >
using	pw::Closure = Function< void()>
	void-returning pw::Function that takes no arguments.
template<typename FunctionType >
using	pw::Callback = fit::callback_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE >
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize>
using	pw::InlineCallback = fit::inline_callback< FunctionType, inline_target_size >
	Version of pw::Callback that exclusively uses inline storage.
template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>
using	pw::DynamicCallback = fit::callback_impl< inline_target_size, false, FunctionType, Allocator >
	Version of pw::Callback that supports dynamic allocation.

Functions
template<auto method, typename T >
auto	pw::bind_member (T *instance)
template<typename FunctionType >
constexpr auto	pw::function::GetFunctionPointer ()
template<typename FunctionType >
constexpr auto	pw::function::GetFunctionPointer (const FunctionType &)
template<typename FunctionType >
constexpr auto	pw::function::GetFunctionPointerContextFirst ()
template<typename FunctionType >
constexpr auto	pw::function::GetFunctionPointerContextFirst (const FunctionType &)
constexpr	pw::ScopeGuard< Functor >::ScopeGuard (Functor &&functor)
constexpr	pw::ScopeGuard< Functor >::ScopeGuard (ScopeGuard &&other) noexcept
template<typename OtherFunctor >
constexpr	pw::ScopeGuard< Functor >::ScopeGuard (ScopeGuard< OtherFunctor > &&other)
ScopeGuard &	pw::ScopeGuard< Functor >::operator= (ScopeGuard &&other) noexcept
	pw::ScopeGuard< Functor >::ScopeGuard (const ScopeGuard &)=delete
ScopeGuard &	pw::ScopeGuard< Functor >::operator= (const ScopeGuard &)=delete
void	pw::ScopeGuard< Functor >::Dismiss ()
template<typename Function >
	pw::ScopeGuard (Function()) -> ScopeGuard< Function(*)()>

Typedef Documentation

Callback

template<typename FunctionType >

using pw::Callback = typedef fit::callback_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>

pw::Callback is identical to pw::Function except:

1. On the first call to invoke a pw::Callback, the target function held by the pw::Callback cannot be called again.
2. When a pw::Callback is invoked for the first time, the target function is released and destructed, along with any resources owned by that function (typically the objects captured by a lambda).

A pw::Callback in the "already called" state has the same state as a pw::Callback that has been assigned to nullptr.

DynamicFunction

template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize, typename Allocator = PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>

using pw::DynamicFunction = typedef fit::function_impl<inline_target_size, false, FunctionType, Allocator>

Version of pw::Function that always supports dynamic allocation.

If dynamic allocation is enabled for pw::Function, pw::Function<FunctionType> is identical to pw::DynamicFunction<FunctionType>.

Template Parameters

Allocator

The Allocator used to dynamically allocate the callable, if it exceeds inline_target_size. Its value_type is irrelevant, since it must support rebinding.

Function

template<typename FunctionType >

using pw::Function = typedef fit::function_impl< function_internal::config::kInlineCallableSize, !function_internal::config::kEnableDynamicAllocation, FunctionType, PW_FUNCTION_DEFAULT_ALLOCATOR_TYPE>

pw::Function is a wrapper for an arbitrary callable object. It can be used by callback-based APIs to allow callers to provide any type of callable.

pw::Function is an alias shared across the Pigweed codebase. External users may configure pw::Function to meet their needs (e.g. more inline storage, support for dynamic memory). Having a shared alias ensures that function objects are interchangeable and keeps code efficient.

Because pw::Function is configurable, upstream Pigweed code must compile against pw::Function's default, minimal configuration: no dynamic memory and a PW_FUNCTION_INLINE_CALLABLE_SIZE of one word.

Almost all upstream Pigweed code should use the default pw::Function. If a different function configuration is needed, use pw::InlineFunction or pw::DynamicFunction. This is not recommended, since this results in increased code size, and conversions between function types are not well optimized.

Example:

template <typename T>
bool All(const pw::Vector<T>& items,
         const pw::Function<bool(const T& item)>& predicate) {
  for (const T& item : items) {
    if (!predicate(item)) {
      return false;
    }
  }
  return true;
}
 
bool ElementsArePositive(const pw::Vector<int>& items) {
  return All(items, [](const int& i) { return i > 0; });
}
 
bool IsEven(const int& i) { return i % 2 == 0; }
 
bool ElementsAreEven(const pw::Vector<int>& items) {
  return All(items, IsEven);
}

InlineFunction

template<typename FunctionType , std::size_t inline_target_size = function_internal::config::kInlineCallableSize>

using pw::InlineFunction = typedef fit::inline_function<FunctionType, inline_target_size>

Version of pw::Function that exclusively uses inline storage.

IMPORTANT: If pw::Function is configured to allow dynamic allocations then any attempt to convert pw::InlineFunction to pw::Function will ALWAYS allocate.

If dynamic allocation is disabled for pw::Function, pw::Function<FunctionType> is identical to pw::InlineFunction<FunctionType>.

Function Documentation

bind_member()

template<auto method, typename T >

auto pw::bind_member

(

T *

instance

)

Returns a Callable which, when called, invokes method on instance using the arguments provided.

This is useful for binding the this argument of a callable.

pw::bind_member<&T::MethodName>(instance) is roughly equivalent to [instance](Arg arg1, ...) { instance->MethodName(arg1, ...) }, albeit with proper support for overloads and argument forwarding.

Dismiss()

template<typename Functor >

void pw::ScopeGuard< Functor >::Dismiss ( )

inline

Dismisses the ScopeGuard, meaning it will no longer execute the Functor when it goes out of scope.

GetFunctionPointer() [1/2]

template<typename FunctionType >

constexpr auto pw::function::GetFunctionPointer ( )

constexpr

Traditional callback APIs often use a function pointer and void* context argument. The context argument makes it possible to use the callback function with non-global data. For example, the qsort_s and bsearch_s functions take a pointer to a comparison function that has void* context as its last parameter. pw::Function does not naturally work with these kinds of APIs.

GetFunctionPointer and GetFunctionPointerContextFirst make it simple to adapt a pw::Function for use with APIs that accept a function pointer and void* context argument.

Returns a function pointer that invokes a pw::Function, lambda, or other callable object from a void* context argument. This makes it possible to use C++ callables with C-style APIs that take a function pointer and void* context.

The returned function pointer has the same return type and arguments as the pw::Function or pw::Callback, except that the last parameter is a void*. GetFunctionPointerContextFirst places the void* context parameter first.

The following example adapts a C++ lambda function for use with C-style API that takes an int (*)(int, void*) function and a void* context.

void TakesAFunctionPointer(int (*function)(int, void*), void* context);
 
void UseFunctionPointerApiWithPwFunction() {
  // Declare a callable object so a void* pointer can be obtained for it.
  auto my_function = [captures](int value) {
     // ...
     return value + captures;
  };
 
  // Invoke the API with the function pointer and callable pointer.
  TakesAFunctionPointer(pw::function::GetFunctionPointer(my_function),
                        &my_function);
}

The function returned from this must ONLY be used with the exact type for which it was created! Function pointer / context APIs are not type safe.

GetFunctionPointer() [2/2]

template<typename FunctionType >

constexpr auto pw::function::GetFunctionPointer ( const FunctionType &  )

constexpr

GetFunctionPointer overload that uses the type of the function passed to this call.

GetFunctionPointerContextFirst() [1/2]

template<typename FunctionType >

constexpr auto pw::function::GetFunctionPointerContextFirst ( )

constexpr

Same as GetFunctionPointer, but the context argument is passed first. Returns a void(void*, int) function for a pw::Function<void(int)>.

GetFunctionPointerContextFirst() [2/2]

template<typename FunctionType >

constexpr auto pw::function::GetFunctionPointerContextFirst ( const FunctionType &  )

constexpr

GetFunctionPointerContextFirst overload that uses the type of the function passed to this call.