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. 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.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.pyx.

Definition at line 91 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(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(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.

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(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< 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>`.

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` `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< 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 95 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 100 of file Delegator.h.

◆ setDelegate() [1/14]

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 105 of file Delegator.h.

◆ setDelegate() [2/14]

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 116 of file Delegator.h.

◆ setDelegate() [3/14]

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 127 of file Delegator.h.

◆ setDelegate() [4/14]

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 138 of file Delegator.h.

◆ setDelegate() [5/14]

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 150 of file Delegator.h.

◆ setDelegate() [6/14]

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 165 of file Delegator.h.

◆ setDelegate() [7/14]

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

inline

Set delegates for member functions with the signature void(span<double>)

Definition at line 177 of file Delegator.h.

◆ setDelegate() [8/14]

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

inline

Set delegates for member functions with the signature void(double, span<double>)

Definition at line 190 of file Delegator.h.

◆ setDelegate() [9/14]

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

inline

Set delegates for member functions with the signature void(double, span<double>, span<double>)

Definition at line 205 of file Delegator.h.

◆ setDelegate() [10/14]

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

inline

Set delegates for member functions with the signature void(span<double>, span<double>, span<double>)

Definition at line 220 of file Delegator.h.

◆ setDelegate() [11/14]

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 234 of file Delegator.h.

◆ setDelegate() [12/14]

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 246 of file Delegator.h.

◆ setDelegate() [13/14]

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 259 of file Delegator.h.

◆ setDelegate() [14/14]

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

inline

Set delegates for member functions with the signature void(SparseTriplets&)

Since: New in Cantera 4.0.

Definition at line 273 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 286 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 294 of file Delegator.h.

◆ install() [1/14]

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 304 of file Delegator.h.

◆ install() [2/14]

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 312 of file Delegator.h.

◆ install() [3/14]

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 320 of file Delegator.h.

◆ install() [4/14]

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 328 of file Delegator.h.

◆ install() [5/14]

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 337 of file Delegator.h.

◆ install() [6/14]

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 347 of file Delegator.h.

◆ install() [7/14]

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

inlineprotected

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

Definition at line 355 of file Delegator.h.

◆ install() [8/14]

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

inlineprotected

Install a function with the signature void(double, span<double>) as being delegatable.

Definition at line 364 of file Delegator.h.

◆ install() [9/14]

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

inlineprotected

Install a function with the signature void(double, span<double>, span<double>) as being delegatable.

Definition at line 374 of file Delegator.h.

◆ install() [10/14]

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

inlineprotected

Install a function with the signature void(span<double>, span<double>, span<double>) as being delegatable.

Definition at line 384 of file Delegator.h.

◆ install() [11/14]

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 393 of file Delegator.h.

◆ install() [12/14]

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 401 of file Delegator.h.

◆ install() [13/14]

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 411 of file Delegator.h.

◆ install() [14/14]

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

inlineprotected

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

Since: New in Cantera 4.0.

Definition at line 423 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 433 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 461 of file Delegator.h.

◆ stripConst()

span< double > stripConst ( const span< const double > & s )

inlineprotected

Helper to remove const for cases where the delegated function signature uses span<const double>.

Definition at line 514 of file Delegator.h.

Member Data Documentation

◆ m_funcs_v

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

protected

Definition at line 544 of file Delegator.h.

◆ m_funcs_v_b

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

protected

Definition at line 545 of file Delegator.h.

◆ m_funcs_v_d

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

protected

Definition at line 546 of file Delegator.h.

◆ m_funcs_v_AMr

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

protected

Definition at line 547 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 548 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 549 of file Delegator.h.

◆ m_funcs_v_dp

map<string, function<void(span<double>)>*> m_funcs_v_dp

protected

Definition at line 550 of file Delegator.h.

◆ m_funcs_v_d_dp

map<string, function<void(double, span<double>)>*> m_funcs_v_d_dp

protected

Definition at line 551 of file Delegator.h.

◆ m_funcs_v_d_dp_dp

map<string, function<void(double, span<double>, span<double>)>*> m_funcs_v_d_dp_dp

protected

Definition at line 553 of file Delegator.h.

◆ m_funcs_v_dp_dp_dp

map<string, function<void(span<double>, span<double>, span<double>)>*> m_funcs_v_dp_dp_dp

protected

Definition at line 555 of file Delegator.h.

◆ m_funcs_v_vET

map<string, function<void(SparseTriplets&)>*> m_funcs_v_vET

protected

Definition at line 556 of file Delegator.h.

◆ m_base_d_vp

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

protected

Definition at line 559 of file Delegator.h.

◆ m_funcs_d_vp

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

protected

Definition at line 560 of file Delegator.h.

◆ m_base_s_sz

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

protected

Definition at line 562 of file Delegator.h.

◆ m_funcs_s_sz

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

protected

Definition at line 563 of file Delegator.h.

◆ m_base_sz_csr

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

protected

Definition at line 565 of file Delegator.h.

◆ m_funcs_sz_csr

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

protected

Definition at line 566 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 572 of file Delegator.h.

◆ m_delegatorName

string m_delegatorName

protected

Name of the class in the extension language.

Definition at line 575 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/14]

◆ setDelegate() [2/14]

◆ setDelegate() [3/14]

◆ setDelegate() [4/14]

◆ setDelegate() [5/14]

◆ setDelegate() [6/14]

◆ setDelegate() [7/14]

◆ setDelegate() [8/14]

◆ setDelegate() [9/14]

◆ setDelegate() [10/14]

◆ setDelegate() [11/14]

◆ setDelegate() [12/14]

◆ setDelegate() [13/14]

◆ setDelegate() [14/14]

◆ holdExternalHandle()

◆ getExternalHandle()

◆ install() [1/14]

◆ install() [2/14]

◆ install() [3/14]

◆ install() [4/14]

◆ install() [5/14]

◆ install() [6/14]

◆ install() [7/14]

◆ install() [8/14]

◆ install() [9/14]

◆ install() [10/14]

◆ install() [11/14]

◆ install() [12/14]

◆ install() [13/14]

◆ install() [14/14]

◆ makeDelegate() [1/2]

◆ makeDelegate() [2/2]

◆ stripConst()

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_funcs_v_vET

◆ 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