PortModules are modules that can be attached to the send and/or receive side of ports. More...

#include <portModule.h>

Inheritance diagram for SST::PortModule:

Public Member Functions
	SST_ELI_DECLARE_INFO_EXTERN (ELI::ProvidesParams, ELI::ProvidesStats, ELI::ProvidesAttributes) PortModule()

virtual uintptr_t	registerLinkAttachTool (const AttachPointMetaData &mdata) override
	Function that will be called when a PortModule is registered on sends (i.e. More...

virtual void	eventSent (uintptr_t key, Event *&ev) override=0
	Function that will be called when an event is sent on a link with registered PortModules. More...

virtual void	serializeEventAttachPointKey (SST::Core::Serialization::serializer &ser, uintptr_t &key) override
	Function that will be called to handle the key returned from registerLinkAttachTool, if the AttachPoint tool is serializable. More...

virtual uintptr_t	registerHandlerIntercept (const AttachPointMetaData &mdata) override
	Function that will be called when a handler is registered with recieves (i.e. More...

virtual void	interceptHandler (uintptr_t key, Event *&data, bool &cancel) override=0
	Function that will be called before the event handler to let the attach point intercept the data. More...

virtual void	serializeHandlerInterceptPointKey (SST::Core::Serialization::serializer &ser, uintptr_t &key) override
	Function that will be called to handle the key returned from registerHandlerIntercept, if the AttachPoint tool is serializable. More...

virtual bool	installOnReceive ()
	Called to determine if the PortModule should be installed on receives. More...

virtual bool	installOnSend ()
	Called to determine if the PortModule should be installed on sends. More...

const std::string &	getName () const

Public Member Functions inherited from SST::Core::Serialization::serializable_base
virtual const char *	cls_name () const =0

virtual uint32_t	cls_id () const =0

virtual std::string	serialization_name () const =0

Protected Member Functions
void	serialize_order (SST::Core::Serialization::serializer &ser) override

UnitAlgebra	getCoreTimeBase () const
	Get the core timebase.

SimTime_t	getCurrentSimCycle () const
	Return the current simulation time as a cycle count.

int	getCurrentPriority () const
	Return the current priority.

UnitAlgebra	getElapsedSimTime () const
	Return the elapsed simulation time as a time.

Output &	getSimulationOutput () const
	Return the base simulation Output class instance.

SimTime_t	getCurrentSimTime (TimeConverter *tc) const
	Return the simulated time since the simulation began in units specified by the parameter. More...

SimTime_t	getCurrentSimTime (TimeConverter &tc) const

SimTime_t	getCurrentSimTime (const std::string &base) const
	Return the simulated time since the simulation began in timebase specified. More...

SimTime_t	getCurrentSimTimeNano () const
	Utility function to return the time since the simulation began in nanoseconds.

SimTime_t	getCurrentSimTimeMicro () const
	Utility function to return the time since the simulation began in microseconds.

SimTime_t	getCurrentSimTimeMilli () const
	Utility function to return the time since the simulation began in milliseconds.

void	fatal (uint32_t line, const char file, const char func, int exit_code, const char *format,...) const
	Convenience function for reporting fatal conditions. More...

void	sst_assert (bool condition, uint32_t line, const char file, const char func, int exit_code, const char *format,...) const
	Convenience function for testing for and reporting fatal conditions. More...

template<typename T >
Statistics::Statistic< T > *	registerStatistic (SST::Params &params, const std::string &stat_name, const std::string &stat_sub_id="")
	Registers a statistic. More...

template<typename T >
Statistics::Statistic< T > *	registerStatistic (const std::string &stat_name, const std::string &stat_sub_id="")

virtual std::string	getEliType () const

Friends
class	BaseComponent

Additional Inherited Members
Static Public Attributes inherited from SST::Core::Serialization::serializable
static constexpr uint32_t	NullClsId = std::numeric_limits<uint32_t>::max()

Static Public Attributes inherited from SST::Core::Serialization::serializable_base
static constexpr uint32_t	NullClsId = std::numeric_limits<uint32_t>::max()

Protected Types inherited from SST::Core::Serialization::serializable_base
enum	cxn_flag_t { ConstructorFlag }

Static Protected Member Functions inherited from SST::Core::Serialization::serializable_base
static void	serializable_abort (uint32_t line, const char file, const char func, const char *obj)

Detailed Description

PortModules are modules that can be attached to the send and/or receive side of ports.

Each PortModule is attached to one port and uses the Event::HandlerBase::InterceptPoint for intercepting incoming events and the Link::AttachPoint to intercept outgoing events. The intercepted events can be inspected, modified and/or canceled. For canceled events, the PortModule is required to delete the event.

NOTE: Not Final API - PortModules will continue to be supported in the future, but the API will not be finalized until the SST 15 release, so there may be slight changes to the base class.

NOTE: Attaching to a port on the send-side has known performance issues, so it is recommended to attach to the input port whenever possible.

Member Function Documentation

◆ eventSent()

virtual void SST::PortModule::eventSent	(	uintptr_t	key,
		Event *&	ev
	)

overridepure virtual

Function that will be called when an event is sent on a link with registered PortModules.

If ev is set to nullptr, then the event will not be delivered and the function should delete the original event.

NOTE: It is possible to delete the incoming event and replace it with a new event, if this is done, the new event MUST call copyAllDeliveryInfo(ev) or the event will not be properly processed.

Parameters

key	Opaque key returned from registerLinkAttachTool()
ev	Event to intercept

Implements SST::Link::AttachPoint.

Implemented in SST::CoreTestPortModule::TestPortModule, and SST::IMPL::PortModule::RandomDrop.

◆ fatal()

void SST::PortModule::fatal	(	uint32_t	line,
		const char *	file,
		const char *	func,
		int	exit_code,
		const char *	format,
			...
	)		const

protected

Convenience function for reporting fatal conditions.

The function will create a new Output object and call fatal() using the supplied parameters. Before calling Output::fatal(), the function will also print other information about the (sub)component that called fatal and about the simulation state.

From Output::fatal: Message will be sent to the output location and to stderr. The output will be prepended with the expanded prefix set in the object. NOTE: fatal() will call MPI_Abort(exit_code) to terminate simulation.

Parameters

line	Line number of calling function (use CALL_INFO macro)
file	File name calling function (use CALL_INFO macro)
func	Function name calling function (use CALL_INFO macro)
exit_code	The exit code used for termination of simulation. will be passed to MPI_Abort()
format	Format string. All valid formats for printf are available.
...	Arguments for format.

◆ getCurrentSimTime() [1/2]

SimTime_t SST::PortModule::getCurrentSimTime ( TimeConverter * tc ) const

protected

Return the simulated time since the simulation began in units specified by the parameter.

Parameters

tc	TimeConverter specifying the units

References SST::BaseComponent::getCurrentSimTime().

◆ getCurrentSimTime() [2/2]

SimTime_t SST::PortModule::getCurrentSimTime ( const std::string & base ) const

protected

Return the simulated time since the simulation began in timebase specified.

Parameters

base	Timebase frequency in SI Units

References SST::BaseComponent::getCurrentSimTime().

◆ installOnReceive()

virtual bool SST::PortModule::installOnReceive ( )

inlinevirtual

Called to determine if the PortModule should be installed on receives.

Returns: true if PortModule should be installed on receives

Reimplemented in SST::CoreTestPortModule::TestPortModule, and SST::IMPL::PortModule::RandomDrop.

◆ installOnSend()

virtual bool SST::PortModule::installOnSend ( )

inlinevirtual

Called to determine if the PortModule should be installed on sends.

NOTE: Installing PortModules on sends will have a noticeable impact on performance, consider architecting things so that you can intercept on receives.

Returns: true if PortModule should be installed on sends

Reimplemented in SST::CoreTestPortModule::TestPortModule, and SST::IMPL::PortModule::RandomDrop.

◆ interceptHandler()

virtual void SST::PortModule::interceptHandler	(	uintptr_t	key,
		Event *&	data,
		bool &	cancel
	)

overridepure virtual

Function that will be called before the event handler to let the attach point intercept the data.

The data can be modified, and if cancel is set to true, the handler will not be executed. If cancel is set to true, then the function should also delete the event and set data to nullptr.

NOTE: It is possible to delete the incoming event and replace the it with a new event, if this is done, the new event MUST call copyAllDeliveryInfo(ev) or the event will not be properly processed.

Parameters

	key	Key returned from registerHandlerIntercept() function
	data	Event that is to be passed to the handler
[out]	cancel	Set to true if the handler delivery should be cancelled. If set to true, function must also delete the event

Implemented in SST::CoreTestPortModule::TestPortModule, and SST::IMPL::PortModule::RandomDrop.

◆ registerHandlerIntercept()

uintptr_t SST::PortModule::registerHandlerIntercept ( const AttachPointMetaData & mdata )

overridevirtual

Function that will be called when a handler is registered with recieves (i.e.

installOnReceive() returns true). The uintptr_t returned from this function will be passed into the intercept() function.

The default implemenation will just return 0 and only needs to be overwritten if the module needs any of the metadata and/or needs to return a unique key.

Parameters

mdata Metadata to be passed into the tool. NOTE: The metadata will be of type EventHandlerMetaData (see sst/core/event.h)

Returns: Opaque key that will be passed back into the interceptHandler() calls

Reimplemented in SST::IMPL::PortModule::RandomDrop.

◆ registerLinkAttachTool()

uintptr_t SST::PortModule::registerLinkAttachTool ( const AttachPointMetaData & mdata )

overridevirtual

Function that will be called when a PortModule is registered on sends (i.e.

installOnSend() returns true). The uintptr_t returned from this function will be passed into the eventSent() function.

The default implemenation will just return 0 and only needs to be overwritten if the module needs any of the metadata and/or needs to return a unique key.

Parameters

mdata Metadata to be passed into the tool. NOTE: The metadata will be of type EventHandlerMetaData (see sst/core/event.h)

Returns: Opaque key that will be passed back into eventSent() to identify the source of the call

Implements SST::Link::AttachPoint.

Reimplemented in SST::IMPL::PortModule::RandomDrop.

◆ registerStatistic()

template<typename T >

Statistics::Statistic<T>* SST::PortModule::registerStatistic	(	SST::Params &	params,
		const std::string &	stat_name,
		const std::string &	stat_sub_id = `""`
	)

inlineprotected

Registers a statistic.

If Statistic is allowed to exist (controlled by Python runtime parameters), then a statistic will be created and returned. If not allowed to exist, then a NullStatistic will be returned. The type of Statistic is set by Python runtime parameters.

Parameters

params	Additional parameter set to be passed to the statistic constructor.
stat_name	Primary name of the statistic. This name must match the defined ElementInfoStatistic in the component, and must also be enabled in the Python input file.
stat_sub_id	An additional sub name for the statistic

Returns: Either a created statistic or a NullStatistic depending upon runtime settings.

◆ serializeEventAttachPointKey()

void SST::PortModule::serializeEventAttachPointKey	(	SST::Core::Serialization::serializer &	ser,
		uintptr_t &	key
	)

overridevirtual

Function that will be called to handle the key returned from registerLinkAttachTool, if the AttachPoint tool is serializable.

This is needed because the key is opaque to the Link, so it doesn't know how to handle it during serialization. During SIZE and PACK phases of serialization, the tool needs to store out any information that will be needed to recreate data that is reliant on the key. On UNPACK, the function needs to recreate the any state and reinitialize the passed in key reference to the proper state to continue to make valid calls to eventSent().

The default implemenation will just set key to 0 on UNPACK and only needs to be overwritten if the module needs to return a unique key from registerLinkAttachTool().

Parameters

ser	Serializer to use for serialization
key	Key that would be passed into the eventSent() function.

Reimplemented from SST::Link::AttachPoint.

◆ serializeHandlerInterceptPointKey()

void SST::PortModule::serializeHandlerInterceptPointKey	(	SST::Core::Serialization::serializer &	ser,
		uintptr_t &	key
	)

overridevirtual

Function that will be called to handle the key returned from registerHandlerIntercept, if the AttachPoint tool is serializable.

This is needed because the key is opaque to the Link, so it doesn't know how to handle it during serialization. During SIZE and PACK phases of serialization, the tool needs to store out any information that will be needed to recreate data that is reliant on the key. On UNPACK, the function needs to recreate any state and reinitialize the passed in key reference to the proper state to continue to make valid calls to interceptHandler().

The default implemenation will just set key to 0 on UNPACK and only needs to be overwritten if the module needs to return a unique key from registerHandlerIntercept().

Parameters

ser	Serializer to use for serialization
key	Key that would be passed into the interceptHandler() function.

◆ sst_assert()

void SST::PortModule::sst_assert	(	bool	condition,
		uint32_t	line,
		const char *	file,
		const char *	func,
		int	exit_code,
		const char *	format,
			...
	)		const

protected

Convenience function for testing for and reporting fatal conditions.

If the condition holds, fatal() will be called, otherwise, the function will return. The function will create a new Output object and call fatal() using the supplied parameters. Before calling Output::fatal(), the function will also print other information about the (sub)component that called fatal and about the simulation state.

From Output::fatal: Message will be sent to the output location and to stderr. The output will be prepended with the expanded prefix set in the object. NOTE: fatal() will call MPI_Abort(exit_code) to terminate simulation.

Parameters

condition	on which to call fatal(); fatal() is called if the bool is false.
line	Line number of calling function (use CALL_INFO macro)
file	File name calling function (use CALL_INFO macro)
func	Function name calling function (use CALL_INFO macro)
exit_code	The exit code used for termination of simulation. will be passed to MPI_Abort()
format	Format string. All valid formats for printf are available.
...	Arguments for format.

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

src/sst/core/portModule.h
src/sst/core/portModule.cc

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ eventSent()

◆ fatal()

◆ getCurrentSimTime() [1/2]

◆ getCurrentSimTime() [2/2]

◆ installOnReceive()

◆ installOnSend()

◆ interceptHandler()

◆ registerHandlerIntercept()

◆ registerLinkAttachTool()

◆ registerStatistic()

◆ serializeEventAttachPointKey()

◆ serializeHandlerInterceptPointKey()

◆ sst_assert()