BifrostGraph Executor Watchpoint. More...

#include <Watchpoint.h>

Classes
struct	Filter
	Structure that holds the filtering settings for getIndices. More...

class	Records
	An interface for the watchpoints to manage recorded values. More...

struct	Sorter
	Structure that holds the sorting settings for getIndices. More...

class	Watcher
	The interface to get the watchpoint layout and value. More...

Public Types
enum class	Field : char { eIndex , eValue , eElement }
	Field enumerants for indices sorter and filters. More...

using	String = Amino::String

using	StringArray = Amino::Array< String >

using	TypeIdArray = Amino::Array< Amino::TypeId >

using	CreateFunc = BifrostGraph::Executor::Watchpoint ()()
	The signature of the function used to create the Watchpoint. More...

using	CallBack = void()(const void clientData, Amino::ulong_t locationID, const void *valueData)
	Callback function signature. More...

using	Filters = Filter::Filters

using	Indices = Amino::Array< std::size_t >

Public Member Functions
	Watchpoint (String name) noexcept
	Constructor. More...

virtual	~Watchpoint () noexcept
	Destructor. More...

String	getName () const noexcept
	Get the name of this Watchpoint for logging purposes. More...

virtual void	deleteThis () noexcept=0
	Instruct the Watchpoint to delete itself. More...

virtual void	getSupportedTypeNames (StringArray &names) const noexcept
	Get the fully qualified names of the types handled by the Watchpoint. More...

virtual void	getSupportedTypeIds (TypeIdArray &typeIds) const noexcept=0
	Get the list of the typeIds handled by this Watchpoint. More...

virtual CallBack	getCallBackFunction (const Amino::TypeId &typeId) const noexcept=0
	Get the callback function for the given typeId. More...

virtual CallBack	getCallBackFunction (const Amino::Type &type) const noexcept
	Get the callback function for the given type. More...

virtual Watcher *	createWatcher (Amino::TypeId const &typeId, Watcher::Flags flags=Watcher::Flags::kNone) const noexcept=0
	Get the watcher for given type. More...

virtual Watcher *	createWatcher (Amino::Type const &type, Watcher::Flags flags=Watcher::Flags::kNone) const noexcept
	Get the watcher for given type. More...

virtual WatchpointLayoutPtr	createLayout (WatchpointLayoutFactory const &factory, Amino::Any const &any) const noexcept
	Create a custom layout for a value of one of the supported types. More...

virtual bool	getValue (WatchpointLayoutFactory const &factory, Amino::Any const &any, WatchpointLayoutPath &path, Amino::String &out_value) const noexcept
	Get the string representation of an element of a given value. More...

virtual bool	getAvailableParameters (const Amino::Type &type, StringArray &parameters) const noexcept
	Get the list of watchable parameters for a given type. More...

virtual bool	getParameterDetails (const Amino::Type &type, const String &parameter, String &description, StringArray &values, StringArray &descriptions) const noexcept
	Get details on the watchable parameter for a given type. More...

virtual const void *	createClientData (const Amino::Type &type, Records &records) const noexcept
	Create a new Watchpoint client data. More...

virtual bool	releaseClientData (const Amino::Type &type, const void *clientData) const noexcept
	Release a Watchpoint client data. More...

virtual bool	getIndices (Amino::Any const &any, Filters const &filters, Sorter const &sorter, Indices &out_indices) const noexcept
	Implemenation helper to return the indices of an array value for given filters and sorter settings. More...

Static Public Member Functions
static const char *	createFuncName () noexcept
	Get the name of the function used to create a new Watchpoint from a shared library. More...

Detailed Description

BifrostGraph Executor Watchpoint.

Watchpoint can be used to handle watchpoint callback and data for specific data types. If the Watchpoint is enabled when executing the Bifrost graph, the callback function of the Watchpoint will be called when transferring the value of an incoming connection to the port to which this Watchpoint belongs.

A Watchpoint should be allocated on the heap, not on the stack. The Workspace will manage its lifetime and delete it by calling Watchpoint::deleteThis when the Workspace gets unloaded.

Definition at line 68 of file Watchpoint.h.

Member Typedef Documentation

◆ CallBack

using BifrostGraph::Executor::Watchpoint::CallBack = void (*)(const void* clientData, Amino::ulong_t locationID, const void* valueData)

Callback function signature.

Definition at line 168 of file Watchpoint.h.

◆ CreateFunc

using BifrostGraph::Executor::Watchpoint::CreateFunc = BifrostGraph::Executor::Watchpoint* (*)()

The signature of the function used to create the Watchpoint.

Definition at line 86 of file Watchpoint.h.

◆ Filters

using BifrostGraph::Executor::Watchpoint::Filters = Filter::Filters

Definition at line 438 of file Watchpoint.h.

◆ Indices

using BifrostGraph::Executor::Watchpoint::Indices = Amino::Array<std::size_t>

Definition at line 439 of file Watchpoint.h.

◆ String

using BifrostGraph::Executor::Watchpoint::String = Amino::String

Definition at line 70 of file Watchpoint.h.

◆ StringArray

using BifrostGraph::Executor::Watchpoint::StringArray = Amino::Array<String>

Definition at line 71 of file Watchpoint.h.

◆ TypeIdArray

using BifrostGraph::Executor::Watchpoint::TypeIdArray = Amino::Array<Amino::TypeId>

Definition at line 72 of file Watchpoint.h.

Member Enumeration Documentation

◆ Field

enum class BifrostGraph::Executor::Watchpoint::Field : char

strong

Field enumerants for indices sorter and filters.

Enumerator
eIndex
eValue
eElement

Definition at line 361 of file Watchpoint.h.

Constructor & Destructor Documentation

◆ Watchpoint()

BifrostGraph::Executor::Watchpoint::Watchpoint ( String name )

explicitnoexcept

Constructor.

Parameters

[in] name The name of this Watchpoint for logging purposes.

◆ ~Watchpoint()

virtual BifrostGraph::Executor::Watchpoint::~Watchpoint ( )

virtualnoexcept

Destructor.

Member Function Documentation

◆ createClientData()

virtual const void * BifrostGraph::Executor::Watchpoint::createClientData	(	const Amino::Type &	type,
		Records &	records
	)		const

virtualnoexcept

Create a new Watchpoint client data.

Deprecated:: Use createWatcher instead.

Parameters

[in]	type	The type of data flowing through the Watchpoint.
[in,out]	records	A reference to a Records object, to query settings and store new values for the parameters.

Returns: An opaque pointer to the new client data.

Note: The default implementation ignores input parameters and returns nullptr.

◆ createFuncName()

static const char * BifrostGraph::Executor::Watchpoint::createFuncName ( )

staticnoexcept

Get the name of the function used to create a new Watchpoint from a shared library.

This function is the C entry point used to register watchpoints with Bifrost. The client code must declare and define the entry point. This function must have the CreateFunc signature.

Note that BIFROSTGRAPH_EXECUTOR_SHARED_DECL is for symbol visiblity, see ExecutorExport.h file.

extern "C" {
BIFROSTGRAPH_EXECUTOR_SHARED_DECL BifrostGraph::Executor::Watchpoint*
createBifrostWatchpoint(void)
 
BIFROSTGRAPH_EXECUTOR_SHARED_DECL BifrostGraph::Executor::Watchpoint*
createBifrostWatchpoint(void) {
    // Return a pointer to my class that implements
    // BifrostGraph::Executor::Watchpoint interface.
    return new MyWatchpoints();
}

The Watchpoint shared library is exposed to Bifrost via a config file. The JSON config file will need a watchPointsTranslationLibs section. Note that, to be portable and depending on the platform, Bifrost config file parsing will automatically add the prefix "lib" and suffix "dll", "so", or "dylib".

{
    "AminoConfigurations": [
        {
            "vendorName": "MyCompany",
            "libraryVersion": "0.0.1",
            "libraryName": "MyPackName",
            "watchPointsTranslationLibs" : [
                {
                    "path": "Directory containing the shared lib",
                    "files": [
                        "MyWatchpoint"
                    ]
                }
            ]
        }
    ]
}

Returns: "createBifrostWatchpoint"

◆ createLayout()

virtual WatchpointLayoutPtr BifrostGraph::Executor::Watchpoint::createLayout	(	WatchpointLayoutFactory const &	factory,
		Amino::Any const &	any
	)		const

virtualnoexcept

Create a custom layout for a value of one of the supported types.

Parameters

factory	The layout factory, used to get/create nested layouts.
any	The value to create the layout for.

Returns: The layout of value on success, or nullptr otherwise.

◆ createWatcher() [1/2]

virtual Watcher * BifrostGraph::Executor::Watchpoint::createWatcher	(	Amino::Type const &	type,
		Watcher::Flags	flags = `Watcher::Flags::kNone`
	)		const

virtualnoexcept

Get the watcher for given type.

Parameters

type	The type of data flowing through the watchpoint.
flags	The watcher flags.

Returns: A pointer to the watcher, or nullptr if type is not supported.

◆ createWatcher() [2/2]

virtual Watcher * BifrostGraph::Executor::Watchpoint::createWatcher	(	Amino::TypeId const &	typeId,
		Watcher::Flags	flags = `Watcher::Flags::kNone`
	)		const

pure virtualnoexcept

Get the watcher for given type.

Parameters

typeId	The typeId of data flowing through the watchpoint.
flags	The watcher flags.

Returns: A pointer to the watcher, or nullptr if type is not supported.

◆ deleteThis()

virtual void BifrostGraph::Executor::Watchpoint::deleteThis ( )

pure virtualnoexcept

Instruct the Watchpoint to delete itself.

◆ getAvailableParameters()

virtual bool BifrostGraph::Executor::Watchpoint::getAvailableParameters	(	const Amino::Type &	type,
		StringArray &	parameters
	)		const

virtualnoexcept

Get the list of watchable parameters for a given type.

Deprecated:: Use createWatcher instead.

Parameters

[in]	type	The Amino type.
[out]	parameters	The list where to return the parameters.

Returns: true if any parameter is available, false otherwise.

Note: The default implementation leaves the output list parameters unchanged and returns false.

◆ getCallBackFunction() [1/2]

virtual CallBack BifrostGraph::Executor::Watchpoint::getCallBackFunction ( const Amino::Type & type ) const

virtualnoexcept

Get the callback function for the given type.

Parameters

[in] type The Amino type.

Returns: The callback function or nullptr if type is not supported.

◆ getCallBackFunction() [2/2]

virtual CallBack BifrostGraph::Executor::Watchpoint::getCallBackFunction ( const Amino::TypeId & typeId ) const

pure virtualnoexcept

Get the callback function for the given typeId.

Parameters

[in] typeId The typeId.

Returns: The callback function or nullptr if typeId is not supported.

◆ getIndices()

virtual bool BifrostGraph::Executor::Watchpoint::getIndices	(	Amino::Any const &	any,
		Filters const &	filters,
		Sorter const &	sorter,
		Indices &	out_indices
	)		const

virtualnoexcept

Implemenation helper to return the indices of an array value for given filters and sorter settings.

Parameters

any	The array value
filters	The list of filters
sorter	The sorting settings
out_indices	The filtered and sorted indices

Returns: True on success, false otherwise.

Note: The default implementation does nothing and returns false.

◆ getName()

String BifrostGraph::Executor::Watchpoint::getName ( ) const

noexcept

Get the name of this Watchpoint for logging purposes.

Returns: The name of this Watchpoint

◆ getParameterDetails()

virtual bool BifrostGraph::Executor::Watchpoint::getParameterDetails	(	const Amino::Type &	type,
		const String &	parameter,
		String &	description,
		StringArray &	values,
		StringArray &	descriptions
	)		const

virtualnoexcept

Get details on the watchable parameter for a given type.

Deprecated:: Use createWatcher instead.

Parameters

[in]	type	The Amino type.
[in]	parameter	The parameter.
[out]	description	The description of the parameter.
[out]	values	The values that can be assigned to the parameter. Can be used as a way to configure the parameter.
[out]	descriptions	The descriptions of each values.

Returns: true if parameter is valid, false otherwise.

Note: The default implementation leaves all output parameters unchanged and returns false.

◆ getSupportedTypeIds()

virtual void BifrostGraph::Executor::Watchpoint::getSupportedTypeIds ( TypeIdArray & typeIds ) const

pure virtualnoexcept

Get the list of the typeIds handled by this Watchpoint.

The Library will call this method to build the list of typeIds handled by this Watchpoint. The default implementation of this method adds no typeId to typeIds. The deriving class may override this default implementation to list the typeIds it handles

Parameters

[out] typeIds The typeIds handled by this Watchpoint.

◆ getSupportedTypeNames()

virtual void BifrostGraph::Executor::Watchpoint::getSupportedTypeNames ( StringArray & names ) const

virtualnoexcept

Get the fully qualified names of the types handled by the Watchpoint.

Deprecated:: Use getSupportedTypeIds instead.

The Library will call this method to build the list of types handled by this Watchpoint. The default implementation of this method adds no type name to names. The deriving class may override this default implementation to list the fully qualified names of the types it handles.

Parameters

[out] names The fully qualified names of the types handled by this Watchpoint.

Note: The default implementation leaves the output list names unchanged.

◆ getValue()

virtual bool BifrostGraph::Executor::Watchpoint::getValue	(	WatchpointLayoutFactory const &	factory,
		Amino::Any const &	any,
		WatchpointLayoutPath &	path,
		Amino::String &	out_value
	)		const

virtualnoexcept

Get the string representation of an element of a given value.

Parameters

	factory	The layout factory, used to get value from nested layouts
	any	The value
	path	The path to the element
[out]	out_value	The string representation

Note: The path is consumed (pop_front) until the final layout element is reached.

Returns: The true if the path was valid, false otherwise.

◆ releaseClientData()

virtual bool BifrostGraph::Executor::Watchpoint::releaseClientData	(	const Amino::Type &	type,
		const void *	clientData
	)		const

virtualnoexcept

Release a Watchpoint client data.

Deprecated:: Use createWatcher instead.

Parameters

[in]	type	The type of data flowing through the Watchpoint.
[in]	clientData	An opaque pointer to the client data allocated by createClientData.

Returns: true if operation was successful, false otherwise.

Note: The default implementation ignores input parameters and returns false.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CallBack

◆ CreateFunc

◆ Filters

◆ Indices

◆ String

◆ StringArray

◆ TypeIdArray

Member Enumeration Documentation

◆ Field

Constructor & Destructor Documentation

◆ Watchpoint()

◆ ~Watchpoint()

Member Function Documentation

◆ createClientData()

◆ createFuncName()

◆ createLayout()

◆ createWatcher() [1/2]

◆ createWatcher() [2/2]

◆ deleteThis()

◆ getAvailableParameters()

◆ getCallBackFunction() [1/2]

◆ getCallBackFunction() [2/2]

◆ getIndices()

◆ getName()

◆ getParameterDetails()

◆ getSupportedTypeIds()

◆ getSupportedTypeNames()

◆ getValue()

◆ releaseClientData()