Delegate member functions of a C++ class to externally-specified functions. More...

#include <Delegator.h>

Inheritance diagram for Delegator:

Detailed Description

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. The std::function has a modified function signature compared to the method that it is replacing or augmenting:

Methods with no return value and scalar arguments are treated the same
Methods with a return value have that value as the first reference argument of their delegate function, and return an int. The delegate should return zero if it does not set the arguments value, and a non-zero value if it does.
Methods with pointers to arrays as arguments have an additional argument introduced to indicate the length of each array argument. This argument occurs either first, or after the return value reference, and is a std::array<size_t, N> where N is the number of array arguments.

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.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. This function type includes the additional std::array argument of array sizes for functions with array arguments.
An override of the member function whose implementation calls the stored delegate. For delegates that need an array of array sizes, this function first calculates the necessary values and passes them as an additional argument to the 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.pyx.

Definition at line 103 of file Delegator.h.

Public Member Functions
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(std::array< size_t, 1 >, double *)> &func, const string &when)
	Set delegates for member functions with the signature `void(double*)`

void	setDelegate (const string &name, const function< void(std::array< size_t, 1 >, double, double *)> &func, const string &when)
	Set delegates for member functions with the signature `void(double, double*)`

void	setDelegate (const string &name, const function< void(std::array< size_t, 2 >, double, double , double )> &func, const string &when)
	Set delegates for member functions with the signature `void(double, double, double)`

void	setDelegate (const string &name, const function< void(std::array< size_t, 3 >, double , double , double *)> &func, const string &when)
	Set delegates for member functions with the signature `void(double, double, 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(size_t &, const string &)> &func, const string &when)
	Set delegates for member functions with the signature `size_t(string)`

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.

Protected Member Functions
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(std::array< size_t, 1 >, double )> &target, const function< void(std::array< size_t, 1 >, double )> &func)
	Install a function with the signature `void(double*)` as being delegatable.

void	install (const string &name, function< void(std::array< size_t, 1 >, double, double )> &target, const function< void(std::array< size_t, 1 >, double, double )> &func)
	Install a function with the signature `void(double, double*)` as being delegatable.

void	install (const string &name, function< void(std::array< size_t, 2 >, double, double , double )> &target, const function< void(std::array< size_t, 2 >, double, double , double )> &func)
	Install a function with the signature `void(double, double, double)` as being delegatable.

void	install (const string &name, function< void(std::array< size_t, 3 >, double , double , double )> &target, const function< void(std::array< size_t, 3 >, double , double , double )> &base)
	Install a function with the signature `void(double, double, 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< size_t(const string &)> &target, const function< size_t(const string &)> &base)
	Install a function with the signature `size_t(string)` 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.

Protected Attributes
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.

Containers for delegates and base class implementations.
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` prefix `c` for `const` arguments suffix `r` for reference arguments suffix `p` for pointer arguments
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(std::array< size_t, 1 >, double )> >	m_funcs_v_dp

map< string, function< void(std::array< size_t, 1 >, double, double )> >	m_funcs_v_d_dp

map< string, function< void(std::array< size_t, 2 >, double, double , double )> * >	m_funcs_v_d_dp_dp

map< string, function< void(std::array< size_t, 3 >, double , double , double )> >	m_funcs_v_dp_dp_dp

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< size_t(const string &)> >	m_base_sz_csr

map< string, function< size_t(const string &)> * >	m_funcs_sz_csr

Member Function Documentation

◆ delegatorName()

string delegatorName ( ) const

inline

Get the name of the user-defined class in the extension language.

Definition at line 107 of file Delegator.h.

◆ setDelegatorName()

void setDelegatorName ( const string & delegatorName )

inline

Set the name of the user-defined class in the extension language.

Definition at line 112 of file Delegator.h.

◆ setDelegate() [1/13]

void setDelegate	(	const string &	name,
		const function< void()> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature void().

Definition at line 117 of file Delegator.h.

◆ setDelegate() [2/13]

void setDelegate	(	const string &	name,
		const function< void(bool)> &	func,
		const string &	when
	)

inline

set delegates for member functions with the signature void(bool)

Definition at line 128 of file Delegator.h.

◆ setDelegate() [3/13]

void setDelegate	(	const string &	name,
		const function< void(double)> &	func,
		const string &	when
	)

inline

set delegates for member functions with the signature void(double)

Definition at line 139 of file Delegator.h.

◆ setDelegate() [4/13]

void setDelegate	(	const string &	name,
		const function< void(AnyMap &)> &	func,
		const string &	when
	)

inline

set delegates for member functions with the signature void(AnyMap&)

Definition at line 150 of file Delegator.h.

◆ setDelegate() [5/13]

void setDelegate	(	const string &	name,
		const function< void(const AnyMap &, const UnitStack &)> &	func,
		const string &	when
	)

inline

set delegates for member functions with the signature void(AnyMap&, UnitStack&)

Definition at line 162 of file Delegator.h.

◆ setDelegate() [6/13]

void setDelegate	(	const string &	name,
		const function< void(const string &, void *)> &	func,
		const string &	when
	)

inline

set delegates for member functions with the signature void(const string&, void*)

Definition at line 177 of file Delegator.h.

◆ setDelegate() [7/13]

void setDelegate	(	const string &	name,
		const function< void(std::array< size_t, 1 >, double *)> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature void(double*)

Definition at line 189 of file Delegator.h.

◆ setDelegate() [8/13]

void setDelegate	(	const string &	name,
		const function< void(std::array< size_t, 1 >, double, double *)> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature void(double, double*)

Definition at line 201 of file Delegator.h.

◆ setDelegate() [9/13]

void setDelegate	(	const string &	name,
		const function< void(std::array< size_t, 2 >, double, double , double )> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature void(double, double*, double*)

Definition at line 216 of file Delegator.h.

◆ setDelegate() [10/13]

void setDelegate	(	const string &	name,
		const function< void(std::array< size_t, 3 >, double , double , double *)> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature void(double*, double*, double*)

Definition at line 231 of file Delegator.h.

◆ setDelegate() [11/13]

void setDelegate	(	const string &	name,
		const function< int(double &, void *)> &	func,
		const string &	when
	)

inline

set delegates for member functions with the signature double(void*)

Definition at line 245 of file Delegator.h.

◆ setDelegate() [12/13]

void setDelegate	(	const string &	name,
		const function< int(string &, size_t)> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature string(size_t)

Definition at line 257 of file Delegator.h.

◆ setDelegate() [13/13]

void setDelegate	(	const string &	name,
		const function< int(size_t &, const string &)> &	func,
		const string &	when
	)

inline

Set delegates for member functions with the signature size_t(string)

Definition at line 270 of file Delegator.h.

◆ holdExternalHandle()

void holdExternalHandle	(	const string &	name,
		const shared_ptr< ExternalHandle > &	handle
	)

inline

Store a handle to a wrapper for the delegate from an external language interface.

Definition at line 283 of file Delegator.h.

◆ getExternalHandle()

shared_ptr< ExternalHandle > getExternalHandle ( const string & name ) const

inline

Get the handle for a wrapper for the delegate from the external language interface specified by name.

Returns a null pointer if the requested handle does not exist.

Definition at line 291 of file Delegator.h.

◆ install() [1/13]

void install	(	const string &	name,
		function< void()> &	target,
		const function< void()> &	func
	)

inlineprotected

Install a function with the signature void() as being delegatable.

Definition at line 301 of file Delegator.h.

◆ install() [2/13]

void install	(	const string &	name,
		function< void(bool)> &	target,
		const function< void(bool)> &	func
	)

inlineprotected

Install a function with the signature void(bool) as being delegatable.

Definition at line 309 of file Delegator.h.

◆ install() [3/13]

void install	(	const string &	name,
		function< void(double)> &	target,
		const function< void(double)> &	func
	)

inlineprotected

Install a function with the signature void(double) as being delegatable.

Definition at line 317 of file Delegator.h.

◆ install() [4/13]

void install	(	const string &	name,
		function< void(AnyMap &)> &	target,
		const function< void(AnyMap &)> &	func
	)

inlineprotected

Install a function with the signature void(AnyMap&) as being delegatable.

Definition at line 325 of file Delegator.h.

◆ install() [5/13]

void install	(	const string &	name,
		function< void(const AnyMap &, const UnitStack &)> &	target,
		const function< void(const AnyMap &, const UnitStack &)> &	func
	)

inlineprotected

Install a function with the signature void(const AnyMap&, const UnitStack&) as being delegatable.

Definition at line 334 of file Delegator.h.

◆ install() [6/13]

void install	(	const string &	name,
		function< void(const string &, void *)> &	target,
		const function< void(const string &, void *)> &	func
	)

inlineprotected

Install a function with the signature `void(const string&, void*) as being delegatable.

Definition at line 344 of file Delegator.h.

◆ install() [7/13]

void install	(	const string &	name,
		function< void(std::array< size_t, 1 >, double *)> &	target,
		const function< void(std::array< size_t, 1 >, double *)> &	func
	)

inlineprotected

Install a function with the signature void(double*) as being delegatable.

Definition at line 352 of file Delegator.h.

◆ install() [8/13]

void install	(	const string &	name,
		function< void(std::array< size_t, 1 >, double, double *)> &	target,
		const function< void(std::array< size_t, 1 >, double, double *)> &	func
	)

inlineprotected

Install a function with the signature void(double, double*) as being delegatable.

Definition at line 361 of file Delegator.h.

◆ install() [9/13]

void install	(	const string &	name,
		function< void(std::array< size_t, 2 >, double, double , double )> &	target,
		const function< void(std::array< size_t, 2 >, double, double , double )> &	func
	)

inlineprotected

Install a function with the signature void(double, double*, double*) as being delegatable.

Definition at line 371 of file Delegator.h.

◆ install() [10/13]

void install	(	const string &	name,
		function< void(std::array< size_t, 3 >, double , double , double *)> &	target,
		const function< void(std::array< size_t, 3 >, double , double , double *)> &	base
	)

inlineprotected

Install a function with the signature void(double*, double*, double*) as being delegatable.

Definition at line 381 of file Delegator.h.

◆ install() [11/13]

void install	(	const string &	name,
		function< double(void *)> &	target,
		const function< double(void *)> &	func
	)

inlineprotected

Install a function with the signature double(void*) as being delegatable.

Definition at line 390 of file Delegator.h.

◆ install() [12/13]

void install	(	const string &	name,
		function< string(size_t)> &	target,
		const function< string(size_t)> &	base
	)

inlineprotected

Install a function with the signature string(size_t) as being delegatable.

Definition at line 398 of file Delegator.h.

◆ install() [13/13]

void install	(	const string &	name,
		function< size_t(const string &)> &	target,
		const function< size_t(const string &)> &	base
	)

inlineprotected

Install a function with the signature size_t(string) as being delegatable.

Definition at line 408 of file Delegator.h.

◆ makeDelegate() [1/2]

template<typename BaseFunc , class ... Args>

function< void(Args ...)> makeDelegate	(	const function< void(Args ...)> &	func,
		const string &	when,
		BaseFunc	base
	)

inlineprotected

Create a delegate for a function with no return value.

Definition at line 419 of file Delegator.h.

◆ makeDelegate() [2/2]

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
	)

inlineprotected

Create a delegate for a function with a return value.

Definition at line 447 of file Delegator.h.

Member Data Documentation

◆ m_funcs_v

map<string, function<void()>*> m_funcs_v

protected

Definition at line 523 of file Delegator.h.

◆ m_funcs_v_b

map<string, function<void(bool)>*> m_funcs_v_b

protected

Definition at line 524 of file Delegator.h.

◆ m_funcs_v_d

map<string, function<void(double)>*> m_funcs_v_d

protected

Definition at line 525 of file Delegator.h.

◆ m_funcs_v_AMr

map<string, function<void(AnyMap&)>*> m_funcs_v_AMr

protected

Definition at line 526 of file Delegator.h.

◆ m_funcs_v_cAMr_cUSr

map<string, function<void(const AnyMap&, const UnitStack&)>*> m_funcs_v_cAMr_cUSr

protected

Definition at line 527 of file Delegator.h.

◆ m_funcs_v_csr_vp

map<string, function<void(const string&, void*)>*> m_funcs_v_csr_vp

protected

Definition at line 528 of file Delegator.h.

◆ m_funcs_v_dp

map<string, function<void(std::array<size_t, 1>, double*)>*> m_funcs_v_dp

protected

Definition at line 529 of file Delegator.h.

◆ m_funcs_v_d_dp

map<string, function<void(std::array<size_t, 1>, double, double*)>*> m_funcs_v_d_dp

protected

Definition at line 530 of file Delegator.h.

◆ m_funcs_v_d_dp_dp

map<string, function<void(std::array<size_t, 2>, double, double*, double*)>*> m_funcs_v_d_dp_dp

protected

Definition at line 532 of file Delegator.h.

◆ m_funcs_v_dp_dp_dp

map<string, function<void(std::array<size_t, 3>, double*, double*, double*)>*> m_funcs_v_dp_dp_dp

protected

Definition at line 534 of file Delegator.h.

◆ m_base_d_vp

map<string, function<double(void*)> > m_base_d_vp

protected

Definition at line 537 of file Delegator.h.

◆ m_funcs_d_vp

map<string, function<double(void*)>*> m_funcs_d_vp

protected

Definition at line 538 of file Delegator.h.

◆ m_base_s_sz

map<string, function<string(size_t)> > m_base_s_sz

protected

Definition at line 540 of file Delegator.h.

◆ m_funcs_s_sz

map<string, function<string(size_t)>*> m_funcs_s_sz

protected

Definition at line 541 of file Delegator.h.

◆ m_base_sz_csr

map<string, function<size_t(const string&)> > m_base_sz_csr

protected

Definition at line 543 of file Delegator.h.

◆ m_funcs_sz_csr

map<string, function<size_t(const string&)>*> m_funcs_sz_csr

protected

Definition at line 544 of file Delegator.h.

◆ m_handles

map<string, shared_ptr<ExternalHandle> > m_handles

protected

Handles to wrappers for the delegated object in external language interfaces.

Used to provide access to these wrappers as well as managing cleanup functions called from the destructor of the derived ExternalHandle class.

Definition at line 550 of file Delegator.h.

◆ m_delegatorName

string m_delegatorName

protected

Name of the class in the extension language.

Definition at line 553 of file Delegator.h.

The documentation for this class was generated from the following file:

Delegator.h

Detailed Description

Implementation for each delegated function type

Implementation for specific delegated functions

Public Member Functions

Protected Member Functions

Protected Attributes

Member Function Documentation

◆ delegatorName()

◆ setDelegatorName()

◆ setDelegate() [1/13]

◆ setDelegate() [2/13]

◆ setDelegate() [3/13]

◆ setDelegate() [4/13]

◆ setDelegate() [5/13]

◆ setDelegate() [6/13]

◆ setDelegate() [7/13]

◆ setDelegate() [8/13]

◆ setDelegate() [9/13]

◆ setDelegate() [10/13]

◆ setDelegate() [11/13]

◆ setDelegate() [12/13]

◆ setDelegate() [13/13]

◆ holdExternalHandle()

◆ getExternalHandle()

◆ install() [1/13]

◆ install() [2/13]

◆ install() [3/13]

◆ install() [4/13]

◆ install() [5/13]

◆ install() [6/13]

◆ install() [7/13]

◆ install() [8/13]

◆ install() [9/13]

◆ install() [10/13]

◆ install() [11/13]

◆ install() [12/13]

◆ install() [13/13]

◆ makeDelegate() [1/2]

◆ makeDelegate() [2/2]

Member Data Documentation

◆ m_funcs_v

◆ m_funcs_v_b

◆ m_funcs_v_d

◆ m_funcs_v_AMr

◆ m_funcs_v_cAMr_cUSr

◆ m_funcs_v_csr_vp

◆ m_funcs_v_dp

◆ m_funcs_v_d_dp

◆ m_funcs_v_d_dp_dp

◆ m_funcs_v_dp_dp_dp

◆ m_base_d_vp

◆ m_funcs_d_vp

◆ m_base_s_sz

◆ m_funcs_s_sz

◆ m_base_sz_csr

◆ m_funcs_sz_csr

◆ m_handles

◆ m_delegatorName