Component bslstl_function_invokerutil [Package bslstl]

Provide invoker adaptors for bsl::function More...

Namespaces
namespace	bslstl

---

Detailed Description

Outline

• Purpose
• Classes
• Macros
• Description
  • Macros
  • Return value of Function_InvokerUtil::invokerForFunc
  • Customization point Function_InvokerUtilNullCheck

Purpose:

Provide invoker adaptors for bsl::function

Classes:

Function_InvokerUtil	Utility for returning an appropriate invoker function
Function_InvokerUtilNullCheck	Customization point to detect null invocable

Macros:

BSLSTL_FUNCTION_INVOKERUTIL_SUPPORT_IS_FUNC_INVOCABLE

defined if supported

See also:

Component bslstl_function

Description:

This component provides a struct, Function_InvokerUtil, containing a function template, invokerForFunc, that returns a pointer to a function that is used to invoke a callable object of a particular type. The returned type is custom-generated for each specific target type. This component is for private use only.

The client of this component, bsl::function, is a complex class that is templated in two ways:

1. The class itself has a template parameter representing the prototype (argument and return types) of its call operator. E.g., type bsl::function<int(char*)> has member int operator()(char*);.
2. Several of its constructors take an argument of template parameter callable type and wrap it, using type erasure, so that the type of the wrapped target is not part of the type of the bsl::function.

Only the invocation mechanism needs both kinds of template parameters; other parts of bsl::function (e.g., bslstl::Function_Rep) concern themselves with only the callable object type, not with the prototype of the call operator. This component factors out most of that complexity so as to minimise code size, especially when using the sim_cpp11_features.pl script to simulate C++11 variadic templates in C++03.

The classes in this component are stateless and contain only static functions.

Macros:

If this component supports checking whether an object of an arbitrary non-cvref-qualified type is invocable under a particular prototype, the BSLSTL_FUNCTION_INVOKERUTIL_SUPPORT_IS_FUNC_INVOCABLE macro is defined, and it is not defined otherwise.

Return value of Function_InvokerUtil::invokerForFunc:

The function pointer, invoker_p, returned by Function_InvokerUtil::invokerForFunc<RET(ARG0, ARG1, ...)> takes an argument of type Function_Rep * and zero or more argument types ARG0, ARG1, ..., as specified by the template argument. Calling invoker_p(rep, arg0, arg1, ...) gets the target, f from rep and invokes it with the supplied arguments. Invocation of f follows the definition of INVOKE in section [func.require] of the C++ standard. These rules are summarized in the following table:

  +----------------------------+-----------------------+
  | Type of target object, 'f' | Invocation expression |
  +============================+=======================+
  | Pointer to function or     | f(arg0, arg1, ...)    |
  | functor class              |                       |
  +----------------------------+-----------------------+
  | Pointer to member function | (arg0X.*f)(arg1, ...) |
  +----------------------------+-----------------------+
  | pointer to data member     | arg0X.*f              |
  +----------------------------+-----------------------+

The arguments to f must be implicitly convertible from the corresponding argument types ARG0, ARG1, ... and the return value of the call expression must be implicitly convertible to RET, unless RET is void.

In the case of a pointer to member function, R (T::*f)(...), or pointer to data member R T::*f, arg0X is one of the following:

• arg0 if ARG0 is T or derived from T.
• arg0.get() if ARG0 is a specialization of reference_wrapper.
• (*arg0) if ARG0 is a pointer type or pointer-like type (e.g., a smart pointer).

Note that, consistent with the C++ Standard definition of INVOKE, we consider pointer-to-member-function and pointer-to-data-member types to be "callable" even though, strictly speaking, they lack an operator().

Customization point Function_InvokerUtilNullCheck:

The class template, Function_InvokerUtilNullCheck<T> provides a single, static member function isNull(const T& f) that returns true iff f represents a "null value". By default, Function_InvokerUtilNullCheck<T>isNull returns true iff T is a pointer or pointer-to-member type and has a null value. For non-pointer types, the primary template always returns false. However, other components can provide specializations of Function_InvokerUtilNullCheck that add the notion of "nullness" to other invocable types. In particular, bslstl_function.h specializes this template for bsl::function and bdef_function.h specializes this template for bdef_function. In both cases, a function object is considered null if it is empty, i.e., it does not wrap an invocable object. Although it is theoretically possible to specialize Function_InvokerUtilNullCheck for types not related to bsl::function, doing so would go outside of the behavior of the standard std::function type that bsl::function is emulating. For this reason, Function_InvokerUtilNullCheck is tucked away in this private component for use only through explicit collaboration.