Delegate member functions of a C++ class to externally-specified functions.
This base class provides functions for setting delegates for the member functions of a C++ class at runtime. The purpose of this capability is to allow the class to be extended using functions defined in any programming language that provides a C API for calling functions in that language.
Delegates are specified as std::function objects that are responsible for encapsulating the data specific to the target language and calling the appropriate function in the target language. For methods with a return value, the std::function has a modified signature where the return value is passed by reference as the first argument and the method returns an int. The delegate should return zero if it does not set the arguments value, and a non-zero value if it does.
Delegated methods can be specified to either "replace" the original class's method, or to run "before" or "after" the original method, using the when parameter of the setDelegate method. There are two special cases for delegates of methods with return values:
- If the "before" delegate specifies a value for the return parameter (and then returns with a non-zero status value), this value will be returned and the original method will not be called. Otherwise, the original method will be called and its value will be returned.
- If an "after" delegate specifies a return value (and returns with a non-zero status value), this value will be added to the value returned by the original method, and this combined result will be then be returned. The meaning of "added" is determined by the + operator for the return type, for example addition for numeric types or concatenation for strings.
Implementation for each delegated function type
Several functions and member variables are defined in this base class for each distinct function signature that can be delegated by a derived class such as ReactorDelegator. These are:
- The install function stores the address of a function that will be called by a derived delegator class in the corresponding m_funcs_... map, and sets the default implementation of this method (which should be to call the base class implementation). For delegates with a return type, a copy of this default implementation is also stored in the corresponding m_base_... map
- The setDelegate function wraps the user-provided delegate in a function that handles whether the delegate is to be called before, after, or instead of the base class's implementation. This function is then stored at the address specified in the corresponding m_funcs_... map.
- m_funcs_... is a mapping between member function names and the addresses of the functions that will be called to implement these functions in the derived delegator class.
- m_base_... is a mapping between member function names and the default implementations of these member functions, for delegates with return values
Additional implementation for each function type is specific to the programming language that the delegate is written in. For the Python delegates, see additional documentation in delegator.py and _delegate_callbacks.pyx.
Implementation for specific delegated functions
Beyond the implementation of particular function signatures, there are no elements of the Delegator class that are specific to individual delegated functions, which are handled by derived classes such as ReactorDelegator, which will also inherit from another base class such as Reactor.
Delegation of a member function (for example, Reactor::eval) is handled by several elements:
- A std::function member variable to hold a delegate function, or its default implementation.
- An override of the member function whose implementation calls the stored delegate.
- A call to install from the constructor of the derived delegator class, which takes the member function name, a reference to the std::function member variable described above, and a lambda function that implements the default behavior, that is, calling the equivalent base class method.
Additional implementation for each function is specific to the programming language that the delegate is written in. For Python delegates, see additional documentation in delegator.py and _delegate_callbacks.pyx.
Definition at line 91 of file Delegator.h.
|
| string | delegatorName () const |
| | Get the name of the user-defined class in the extension language.
|
| void | setDelegatorName (const string &delegatorName) |
| | Set the name of the user-defined class in the extension language.
|
| void | setDelegate (const string &name, const function< void()> &func, const string &when) |
| | Set delegates for member functions with the signature void().
|
| void | setDelegate (const string &name, const function< void(bool)> &func, const string &when) |
| | set delegates for member functions with the signature void(bool)
|
| void | setDelegate (const string &name, const function< void(double)> &func, const string &when) |
| | set delegates for member functions with the signature void(double)
|
| void | setDelegate (const string &name, const function< void(AnyMap &)> &func, const string &when) |
| | set delegates for member functions with the signature void(AnyMap&)
|
| void | setDelegate (const string &name, const function< void(const AnyMap &, const UnitStack &)> &func, const string &when) |
| | set delegates for member functions with the signature void(AnyMap&, UnitStack&)
|
| void | setDelegate (const string &name, const function< void(const string &, void *)> &func, const string &when) |
| | set delegates for member functions with the signature void(const string&, void*)
|
| void | setDelegate (const string &name, const function< void(span< double >)> &func, const string &when) |
| | Set delegates for member functions with the signature void(span<double>).
|
| void | setDelegate (const string &name, const function< void(double, span< double >)> &func, const string &when) |
| | Set delegates for member functions with the signature void(double, span<double>).
|
| void | setDelegate (const string &name, const function< void(double, span< double >, span< double >)> &func, const string &when) |
| | Set delegates for member functions with the signature void(double, span<double>, span<double>).
|
| void | setDelegate (const string &name, const function< void(span< double >, span< double >, span< double >)> &func, const string &when) |
| | Set delegates for member functions with the signature void(span<double>, span<double>, span<double>).
|
| void | setDelegate (const string &name, const function< int(double &, void *)> &func, const string &when) |
| | set delegates for member functions with the signature double(void*)
|
| void | setDelegate (const string &name, const function< int(string &, size_t)> &func, const string &when) |
| | Set delegates for member functions with the signature string(size_t).
|
| void | setDelegate (const string &name, const function< int(double &, size_t)> &func, const string &when) |
| | Set delegates for member functions with the signature double(size_t).
|
| void | setDelegate (const string &name, const function< int(size_t &, const string &)> &func, const string &when) |
| | Set delegates for member functions with the signature size_t(string).
|
| void | setDelegate (const string &name, const function< void(SparseTriplets &)> &func, const string &when) |
| | Set delegates for member functions with the signature void(SparseTriplets&).
|
| void | holdExternalHandle (const string &name, const shared_ptr< ExternalHandle > &handle) |
| | Store a handle to a wrapper for the delegate from an external language interface.
|
| shared_ptr< ExternalHandle > | getExternalHandle (const string &name) const |
| | Get the handle for a wrapper for the delegate from the external language interface specified by name.
|
|
| void | install (const string &name, function< void()> &target, const function< void()> &func) |
| | Install a function with the signature void() as being delegatable.
|
| void | install (const string &name, function< void(bool)> &target, const function< void(bool)> &func) |
| | Install a function with the signature void(bool) as being delegatable.
|
| void | install (const string &name, function< void(double)> &target, const function< void(double)> &func) |
| | Install a function with the signature void(double) as being delegatable.
|
| void | install (const string &name, function< void(AnyMap &)> &target, const function< void(AnyMap &)> &func) |
| | Install a function with the signature void(AnyMap&) as being delegatable.
|
| void | install (const string &name, function< void(const AnyMap &, const UnitStack &)> &target, const function< void(const AnyMap &, const UnitStack &)> &func) |
| | Install a function with the signature void(const AnyMap&, const UnitStack&) as being delegatable.
|
| void | install (const string &name, function< void(const string &, void *)> &target, const function< void(const string &, void *)> &func) |
| | Install a function with the signature void(const string&, void*) as being delegatable.
|
| void | install (const string &name, function< void(span< double >)> &target, const function< void(span< double >)> &func) |
| | Install a function with the signature void(span<double>) as being delegatable.
|
| void | install (const string &name, function< void(double, span< double >)> &target, const function< void(double, span< double >)> &func) |
| | Install a function with the signature void(double, span<double>) as being delegatable.
|
| void | install (const string &name, function< void(double, span< double >, span< double >)> &target, const function< void(double, span< double >, span< double >)> &func) |
| | Install a function with the signature void(double, span<double>, span<double>) as being delegatable.
|
| void | install (const string &name, function< void(span< double >, span< double >, span< double >)> &target, const function< void(span< double >, span< double >, span< double >)> &base) |
| | Install a function with the signature void(span<double>, span<double>, span<double>) as being delegatable.
|
| void | install (const string &name, function< double(void *)> &target, const function< double(void *)> &func) |
| | Install a function with the signature double(void*) as being delegatable.
|
| void | install (const string &name, function< string(size_t)> &target, const function< string(size_t)> &base) |
| | Install a function with the signature string(size_t) as being delegatable.
|
| void | install (const string &name, function< double(size_t)> &target, const function< double(size_t)> &base) |
| | Install a function with the signature double(size_t) as being delegatable.
|
| void | install (const string &name, function< size_t(const string &)> &target, const function< size_t(const string &)> &base) |
| | Install a function with the signature size_t(string) as being delegatable.
|
| void | install (const string &name, function< void(SparseTriplets &)> &target, const function< void(SparseTriplets &)> &base) |
| | Install a function with the signature void(SparseTriplets&) as being delegatable.
|
| template<typename BaseFunc, class ... Args> |
| function< void(Args ...)> | makeDelegate (const function< void(Args ...)> &func, const string &when, BaseFunc base) |
| | Create a delegate for a function with no return value.
|
| template<typename ReturnType, class ... Args> |
| function< ReturnType(Args ...)> | makeDelegate (const string &name, const function< int(ReturnType &, Args ...)> &func, const string &when, const function< ReturnType(Args ...)> &base) |
| | Create a delegate for a function with a return value.
|
| span< double > | stripConst (const span< const double > &s) |
| | Helper to remove const for cases where the delegated function signature uses span<const double>.
|
|
| map< string, shared_ptr< ExternalHandle > > | m_handles |
| | Handles to wrappers for the delegated object in external language interfaces.
|
| string | m_delegatorName |
| | Name of the class in the extension language.
|
Maps named m_funcs_* hold the current delegate.
For functions with a return value, m_base_* holds a pointer to the base class's implementation of the function.
These containers use a naming scheme based on the signature of the corresponding member functions. Following the prefix _m_funcs_ is a notation of the return type, followed by an underscore, then the notations for each argument, separated by underscores. The following shorthand is used for different return / argument types:
- v for void
- b for bool
- d for double
- s for string
- sz for size_t
- AM for AnyMap
- US for UnitStack
- ET for Eigen::Triplet<double>
- prefix c for const arguments
- suffix r for reference arguments
- suffix p for span arguments (for example, dp for span<double>)
|
| map< string, function< void()> * > | m_funcs_v |
| map< string, function< void(bool)> * > | m_funcs_v_b |
| map< string, function< void(double)> * > | m_funcs_v_d |
| map< string, function< void(AnyMap &)> * > | m_funcs_v_AMr |
| map< string, function< void(const AnyMap &, const UnitStack &)> * > | m_funcs_v_cAMr_cUSr |
| map< string, function< void(const string &, void *)> * > | m_funcs_v_csr_vp |
| map< string, function< void(span< double >)> * > | m_funcs_v_dp |
| map< string, function< void(double, span< double >)> * > | m_funcs_v_d_dp |
| map< string, function< void(double, span< double >, span< double >)> * > | m_funcs_v_d_dp_dp |
| map< string, function< void(span< double >, span< double >, span< double >)> * > | m_funcs_v_dp_dp_dp |
| map< string, function< void(SparseTriplets &)> * > | m_funcs_v_vET |
| map< string, function< double(void *)> > | m_base_d_vp |
| map< string, function< double(void *)> * > | m_funcs_d_vp |
| map< string, function< string(size_t)> > | m_base_s_sz |
| map< string, function< string(size_t)> * > | m_funcs_s_sz |
| map< string, function< double(size_t)> > | m_base_d_sz |
| map< string, function< double(size_t)> * > | m_funcs_d_sz |
| map< string, function< size_t(const string &)> > | m_base_sz_csr |
| map< string, function< size_t(const string &)> * > | m_funcs_sz_csr |