| Cantera 3.0.0

Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Delegator Class Reference

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

`#include <Delegator.h>`

Inheritance diagram for Delegator:
[legend]

## 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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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
| ) |  |
| inline protected

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