codi::EventSystemBase< T_Tape > Struct Template Reference

Base class for the CoDiPack event system. More...

#include <eventSystem.hpp>

Inheritance diagram for codi::EventSystemBase< T_Tape >:

Public Types
using	Handle = size_t
	Handle that identifies a registered callback.
using	Identifier = typename Tape::Identifier
	Identifier type used by the tape.
using	Real = typename Tape::Real
	Floating point type the tape is based on.
using	Tape = T_Tape
	See EventSystemBase.

Static Public Member Functions
Statement events
static Handle	registerStatementPrimalListener (void(*callback)(Tape &, Real const &, Identifier const &, Real const &, EventHints::Statement, void *), void *customData=nullptr)
	Register callbacks for StatementPrimal events.
static void	notifyStatementPrimalListeners (Tape &tape, Real const &lhsValue, Identifier const &lhsIdentifier, Real const &newValue, EventHints::Statement statement)
	Invoke callbacks for StatementPrimal events.
static void	notifyStatementPrimalListeners (Tape &&tape, Real const &lhsValue, Identifier const &lhsIdentifier, Real const &newValue, EventHints::Statement statement)
	Invoke callbacks for StatementPrimal events.
General methods
static void	deregisterListener (Handle const &handle)
	Deregister a listener.

Protected Types
using	Callback = void*
enum class	Event {   TapeStartRecording , TapeStopRecording , TapeRegisterInput , TapeRegisterOutput ,   TapeEvaluate , TapeReset , PreaccStart , PreaccFinish ,   PreaccAddInput , PreaccAddOutput , StatementPrimal , StatementStoreOnTape ,   StatementEvaluate , StatementEvaluatePrimal , IndexCreate , IndexAssign ,   IndexFree , IndexCopy , Count }
	Full set of events.
using	EventListenerMap = std::map<Event, std::list<std::pair<Handle, std::pair<Callback, void*>>>>
	Map that links events to registered callbacks and their associated custom data.

Static Protected Member Functions
static EventListenerMap &	getListeners ()
	Access the static EventListenerMap.
template<typename TypedCallback , typename... Args>
static void	internalNotifyListeners (bool const enabled, Event event, Args &&... args)
	Internal method for callback invocation.
template<typename TypedCallback >
static Handle	internalRegisterListener (bool const enabled, Event event, TypedCallback callback, void *customData)
	Internal method for callback registration.

Detailed Description

template<typename T_Tape>
struct codi::EventSystemBase< T_Tape >

Base class for the CoDiPack event system.

CoDiPack provides an event system that can be used to, e.g.,

• gain insight into CoDiPack's internal workflow,
• debug AD, from the coarse AD workflow to the individual statements,
• insert custom functionality into CoDiPack's workflow,
• monitor the performance of individual AD constructs.

For this, a set of events is defined and for each event, custom callbacks can be registered. As the event occurs, CoDiPack invokes the custom callbacks and passes them details about the event itself and related AD data. AD workflow events are enabled by default. All other events need to be enable with the corresponding switches in codi::Config, e.g. Config::StatementEvents.

A callback is registered by a register*Listener call and is subsequently invoked by CoDiPack by the corresponding notify*Listeners call. Please refer to the individual register*Listener functions for the callback signatures. Each callback can be associated with custom data that is provided to each callback invocation. This can be used, e.g., to register the same callback function multiple times with different data. The functions are written such that the required callback signatures should be displayed by code completion tools and IDE tooltips.

The event system is a tape-specific, global entity that is shared by all tapes of the same type. Different tape types use different event systems, e.g., second order types have different event systems for outer and inner tapes.

This base class defines general functionality as well as methods for the StatementPrimal event that is common to forward and reverse tapes.

Template Parameters

T_Tape

Tape type associated with the event system.

Member Typedef Documentation

Callback

template<typename T_Tape >

using codi::EventSystemBase< T_Tape >::Callback = void*

protected

Internal, typeless callback storage.

Member Function Documentation

deregisterListener()

template<typename T_Tape >

static void codi::EventSystemBase< T_Tape >::deregisterListener ( Handle const & handle )

inlinestatic

Deregister a listener.

To deregister a listener, use the handle that was returned upon registration.

Parameters

handle

Handle of the listener that should be deregistered.

getListeners()

template<typename T_Tape >

static EventListenerMap & codi::EventSystemBase< T_Tape >::getListeners ( )

inlinestaticprotected

Access the static EventListenerMap.

Both tapes and event systems are static entities in CoDiPack, but the tape depends on the event system. We ensure with an initialize-on-first-use pattern that the event system is available when needed. Ensures that the event listener map has empty entries for all events, so that its size does not change any more. This is important in a shared memory setting when multiple threads access the listener map simultaneously.

internalNotifyListeners()

template<typename T_Tape >

template<typename TypedCallback , typename... Args>

static void codi::EventSystemBase< T_Tape >::internalNotifyListeners ( bool const enabled, Event event, Args &&... args )

inlinestaticprotected

Internal method for callback invocation.

Invokes all callbacks stored for the given event in the static EventListenerMap. Passes associated custom data to the callback.

Parameters

enabled	Whether or not the event is active, obtained from Config.
event	The event for which we register a callback.
args	Arguments for the callback.

Template Parameters

TypedCallback	Type of the callback to invoke.
Args	Types of the callback arguments.

internalRegisterListener()

template<typename T_Tape >

template<typename TypedCallback >

static Handle codi::EventSystemBase< T_Tape >::internalRegisterListener ( bool const enabled, Event event, TypedCallback callback, void * customData )

inlinestaticprotected

Internal method for callback registration.

Stores the callback together with customData in the event entry of the static EventListenerMap.

Parameters

enabled	Whether or not the event is active, obtained from Config.
event	The event for which we register a callback.
callback	The callback to register.
customData	A pointer to custom data that is provided whenever the callback is invoked.

Template Parameters

TypedCallback

Type of the callback to register.

Returns

Handle that can be used to deregister this listener. A handle of 0 means that nothing was registered.

notifyStatementPrimalListeners() [1/2]

template<typename T_Tape >

static void codi::EventSystemBase< T_Tape >::notifyStatementPrimalListeners ( Tape && tape, Real const & lhsValue, Identifier const & lhsIdentifier, Real const & newValue, EventHints::Statement statement )

inlinestatic

Invoke callbacks for StatementPrimal events.

See notifyStatementPrimalListeners(Tape&, Real const&, Identifier const&, Real const&, EventHints::Statement) for details.

notifyStatementPrimalListeners() [2/2]

template<typename T_Tape >

static void codi::EventSystemBase< T_Tape >::notifyStatementPrimalListeners ( Tape & tape, Real const & lhsValue, Identifier const & lhsIdentifier, Real const & newValue, EventHints::Statement statement )

inlinestatic

Invoke callbacks for StatementPrimal events.

A StatementPrimal event is triggered whenever an assignment (e.g. x = ...) or construction (e.g. x(...)) with some ActiveType x is executed.

In case of an assignment, the callback is invoked before the assignment is executed. In case of a constructor, the order of callback invocation and assignment is unspecified.

Parameters

tape	Reference to the tape.
lhsValue	Value of the left hand side before the assignment.
lhsIdentifier	Identifier (or gradient in forward mode) of the left hand side before the assignment.
newValue	Value of the right hand side that is assigned.
statement	Classifies the statement.

registerStatementPrimalListener()

template<typename T_Tape >

static Handle codi::EventSystemBase< T_Tape >::registerStatementPrimalListener ( void(*)(Tape &, Real const &, Identifier const &, Real const &, EventHints::Statement, void *) callback, void * customData = nullptr )

inlinestatic

Register callbacks for StatementPrimal events.

See notifyStatementPrimalListeners for callback parameters and event order.

Parameters

callback	Callback to be invoked.
customData	Optional. Custom data that should be linked with the callback, otherwise nullptr.

---

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

• include/codi/misc/eventSystem.hpp