omni::function< TReturn(TArgs…)>

Defined in omni/Function.h

template<typename TReturn, typename ...TArgs>
class function<TReturn(TArgs...)> : private omni::detail::FunctionData

A polymorphic function wrapper which is compatible with std::function.

For most usage, it is equivalent to the std::function API, but there are a few minor changes for ABI stability and C interoperation.

  • The target and target_type functions are not available. These rely on RTTI, which is not required for Omniverse builds and is not ABI safe.

  • No support for allocators, as these were removed in C++17. The carbReallocate function is used for all memory management needs.

  • A local buffer for storing functors. While the C++ Standard encourages this, this implementation keeps the size and alignment fixed.

  • An omni::function is trivially-relocatable.

Public Types

using result_type = typename traits::result_type

The return type of this function.

Public Functions

inline function(std::nullptr_t) noexcept

Create an unbound instance.

inline function() noexcept

Create an unbound instance.

function(function const &other) = default

Create an instance as a copy of other.

If other was bound before the call, then the created instance will be bound to the same target.

function(function &&other) noexcept = default

Create an instance by moving from other.

If other was bound before the call, then the created instance will be bound to the same target. After this call, other will be unbound.

inline function &operator=(std::nullptr_t) noexcept

Reset this function wrapper to unbound.

function &operator=(function const &other) = default

Copy the other instance into this one.

If copying the function fails, both instances will remain unchanged.

function &operator=(function &&other) noexcept = default

Move the other instance into this one.

template<typename F, typename Assigner = ::omni::detail::FunctionAssigner<traits, F>>
inline function(F &&f)

The binding constructor for function, which wraps f for invocation.

The created instance will have a “target type” (referred to as Target here) of std::decay_t<Target> which is responsible for invoking the function. The following descriptions use a common set of symbols to describe types:

  • UReturn &#8212; A return type which is the same as or implicitly convertible from TReturn. If UReturn is void, then TReturn must be implicitly discardable.

  • UArgs… &#8212; An argument pack where all arguments are implicitly convertible to TArgs… .

  • UArg0Obj &#8212; The object type of the possibly-dereferenced first type in the TArgs… pack. In other words, if TArgs… was {Object*, int}, then UArg0Obj would be Object. Any cv-qualifiers follow the dereference (e.g.: if TArg0 is Object const*, then UArg0Obj is Object const).

  • UArg1N… &#8212; Same as UArgs… but do not include the first type in the pack.

The Target can be one of the following:

  1. A function pointer &#8212; UReturn(*)(UArgs…)

  2. A pointer to a member function &#8212; UReturn UArg0Obj::*(UArg1N...)

  3. A pointer to member data &#8212; UReturn UArg0Obj::* when sizeof(TArgs...) == 1

  4. Another omni::function &#8212; omni::function<UReturn(UArgs...)> where UReturn and UArgs… are different from TReturn and TArgs… (the exact same type uses a copy or move operation)

  5. An std::function &#8212; std::function<UReturn(UArgs...)>, but UReturn and UArgs… can all match TReturn and TArgs…

  6. A functor with operator() accepting UArgs… and returning UReturn

If the Target does not match any of preceding possibilities, this function does not participate in overload resolution in a SFINAE-safe manner. If Target is non-copyable, then the program is ill-formed.

For cases 1-5, if f == nullptr, then the function is initialized as unbound. Note the quirky case on #6, where the composite omni::function<void()>{std::function<void()>{}} will create an unbound function. But this is not commutative, as std::function<void()>{omni::function<void()>{}} will create a bound function which throws when called.

template<typename F, typename Assigner = ::omni::detail::FunctionAssigner<traits, F>>
inline function &operator=(F &&f)

Bind this instance to f according to the rules in the binding constructor.

If the process of binding a function to f fails, this instance will remain unchanged.

~function() noexcept = default

If this function has context it needs to destroy, then perform that cleanup.

inline TReturn operator()(TArgs... args) const

Invoke this function with the provided args.

If this function is not bound (see operator bool() const), the program will throw bad_function_call if exceptions are enabled or panic if they are not.

inline explicit operator bool() const noexcept

Check that this function is bound.

inline void swap(function &other) noexcept

Swap the contents of other with this one.