Represents a general capsule port typed by a protocol which determines the set of events that can be sent to and received by the port. More...

#include <RTProtocol.h>

Inheritance diagram for RTProtocol:

Public Member Functions
RTController *	context (void) const
	Get the context of the capsule that owns this port.

int	getId (void) const
	Get the id of the port.

const RTPortDescriptor *	getInfo (void) const
	Get information about a port.

const char *	getName (void) const
	Get the name of the port.

RTActor *	getOwner (void) const
	Get the owner capsule to which the port belongs.

int	size (void) const
	Get the size of the port.

int	resize (int new_size)
	Set a new size (i.e.

int	registerSAP (const char *service)
	Register an unwired port (SAP) with the layer service (as a "client").

int	deregisterSAP (void)
	Deregister an unwired port (SAP).

int	registerSPP (const char *service)
	Register an unwired port (SPP) with the layer service (as the "provider").

int	deregisterSPP (void)
	Deregister an unwired port (SPP).

const char *	defaultLayerName (void) const
	Get the default registration name for the port.

int	isRegistered (void) const
	Determine if the port is currently registered with the layer service or not.

const char *	getRegisteredName (void) const
	Get the registration name of the port.

int	registerAs (const char *service)
	Register an unwired port either as an SAP or SPP (depending on the "Publish" property of the port).

int	deregister (void)
	Deregister an unwired port (either an SAP or SPP).

int	isBoundAt (int index) const
	Determine if a port instance is currently connected to another port instance.

int	isIndexTo (int index, RTActor *capsule) const
	Determine if a port instance is currently connected to a port instance owned by a certain capsule instance.

int	indexTo (RTActor *capsule) const
	Determine if there exists a port instance currently connected to a port instance owned by a certain capsule instance.

int	purge (void)
	Empty the defer queue of all port instances without recalling any deferred message.

int	purgeAt (int index)
	Empty the defer queue of a specified port instance without recalling any deferred message.

int	recall (void)
	Recall a message from the defer queue and insert it at the back of the controller's message queue (after other queued messages).

int	recallFront (void)
	Recall a message from the defer queue and insert it at the front of the controller's message queue (before other queued messages).

int	recallAt (int index, int front=0)
	Recall a message from the defer queue and insert it in the controller's message queue.

int	recallAll (void)
	Recall all messages from the defer queue and insert them at the back of the controller's message queue (after other queued messages).

int	recallAllFront (void)
	Recall all messages from the defer queue and insert them at the front of the controller's message queue (before other queued messages).

int	recallAllAt (int index, int front=0)
	Recall all messages from the defer queue and insert them in the controller's message queue.

void	bindingNotification (int on_off)
	Turn on or off binding notifications for this port.

int	bindingNotificationRequested (void) const
	Determine if binding notifications are currently enabled for the port.

void	sendTypeCheckEnable (int on_off)
	Turn on or off type checking when performing send(), invoke() or reply() on the port.

int	sendTypeCheckEnabled (void) const
	Determine if type checking when sending events is enabled.

RTProtocolDescriptor::Status	sendCheck (int signal, const RTObject_class *type) const
	Check if a particular event would be possible to send on this port.

void	receiveTypeCheckEnable (int on_off)
	Turn on or off type checking when receiving an event on the port.

int	receiveTypeCheckEnabled (void) const
	Determine if type checking when receiving events is enabled.

RTProtocolDescriptor::Status	receiveCheck (int signal, const RTObject_class *type) const
	Check if a particular event would be possible to receive on this port.

int	invoke (RTMessage replyBuffer, int signal, const void data, const RTObject_class *type, bool implicitReply)
	Invoke an event on the port.

int	invokeAt (int index, RTMessage replyBuffer, int signal, const void data, const RTObject_class *type, bool implicitReply)
	Invoke an event on a replicated port at a specified index.

int	reply (int signal, const void data, const RTObject_class type)
	Make a reply to respond to an invoke.

int	send (int signal, const void data, const RTObject_class type, int priority, bool moveData=false)
	Send an event on the port.

int	sendAt (int index, int signal, const void data, const RTObject_class type, int priority, bool moveData=false)
	Send an event on a replicated port at a specified index.

Protected Types
enum	{ BindingNotification = 1 , RegisteredAsSAP = 2 , SendTypeCheck = 4 , ReceiveTypeCheck = 8 , Resized = 16 }

enum	{ rtiLast_RTProtocol = 0 }

Protected Member Functions
void	init (const RTPortDescriptor *)

int	getFlags (void) const

void	setFlag (int)

void	resetFlag (int)

void	bindAt (int, RTBindingEnd &, RTController *)

int	peerAt (int, RTBindingEnd &)

void	unbindAt (int, RTController *)

void	notifyInit (RTController *)

void	notifyBoundAt (int, RTController *)

Friends
struct	End

class	RTActor

class	RTActorProbe

class	RTDebugger

class	RTLayerConnector

struct	RTExceptionSignal

struct	RTInSignal

struct	RTOutSignal

struct	RTSymmetricSignal

Detailed Description

Represents a general capsule port typed by a protocol which determines the set of events that can be sent to and received by the port.

All specific protocols inherit from RTProtocol, which means that the functions of this class can be called on any capsule port regardless of which protocol it is typed by. For all protocols defined in the application two subclasses of RTProtocol are generated; one for each direction of communication using the events defined in the protocol. For a protocol X these subclasses are X::Base and X::Conjugate.

Member Function Documentation

◆ bindingNotification()

void RTProtocol::bindingNotification ( int on_off )

Turn on or off binding notifications for this port.

When such notifications are turned on the port will receive the 'rtBound' and 'rtUnbound' messages each time a port instance gets connected to (bound) or disconnected from (unbound) a remote port instance. Note that no messages are sent for port instances that are bound prior to the call of this function. Also note that turning off binding notifications will not purge 'rtBound' and 'rtUnbound' messages that have already been queued.

Parameters

on_off Set to 0 to turn off binding notifications for the port, and 1 (or any non-zero value) to turn them on.

◆ bindingNotificationRequested()

int RTProtocol::bindingNotificationRequested ( void ) const

Determine if binding notifications are currently enabled for the port.

Returns: 1 if binding notifications have been turned on for this port, 0 otherwise.

◆ context()

RTController * RTProtocol::context ( void ) const

Get the context of the capsule that owns this port.

Returns: The controller that runs the capsule instance to which this port belongs.

◆ defaultLayerName()

const char * RTProtocol::defaultLayerName ( void ) const

Get the default registration name for the port.

Returns: The default registration name specified for the unwired port. This corresponds to the port property "Registration Override".

◆ deregister()

int RTProtocol::deregister ( void )

Deregister an unwired port (either an SAP or SPP).

This is equivalent of calling deregisterSAP() or deregisterSPP().

Returns: 1 if deregistration was successful, 0 otherwise.

◆ deregisterSAP()

int RTProtocol::deregisterSAP ( void )

Deregister an unwired port (SAP).

If the port is currently connected to an SPP, the connection will be terminated.

Returns: 1 if deregistration was successful, 0 otherwise.

◆ deregisterSPP()

int RTProtocol::deregisterSPP ( void )

Deregister an unwired port (SPP).

If the port is currently connected to SPPs, all those connections will be terminated.

Returns: 1 if deregistration was successful, 0 otherwise.

◆ getId()

int RTProtocol::getId ( void ) const

Get the id of the port.

Returns: An id that is unique among all the ports of the owner capsule.

◆ getInfo()

const RTPortDescriptor * RTProtocol::getInfo ( void ) const

Get information about a port.

Returns: An RTPortDescriptor object that contains information about the port. This information is static and is constituted by properties of the port definition, such as the name of the port.

◆ getName()

const char * RTProtocol::getName ( void ) const

Get the name of the port.

Returns: The name of the port.

◆ getOwner()

RTActor * RTProtocol::getOwner ( void ) const

Get the owner capsule to which the port belongs.

Returns: The RTActor representing the capsule to which this port belongs.

◆ getRegisteredName()

const char * RTProtocol::getRegisteredName ( void ) const

Get the registration name of the port.

Returns: The name under which the unwired port is currently registered with the layer service.

◆ indexTo()

int RTProtocol::indexTo ( RTActor * capsule ) const

Determine if there exists a port instance currently connected to a port instance owned by a certain capsule instance.

If so, the index of the first found matching port instance is returned.

Parameters

capsule Capsule instance

Returns: The smallest index found for a port instance connected to another port instance that is owned by the specified capsule instance. -1 if no such port instance exists.

◆ invoke()

int RTProtocol::invoke	(	RTMessage *	replyBuffer,
		int	signal,
		const void *	data,
		const RTObject_class *	type,
		bool	implicitReply
	)

Invoke an event on the port.

Normally you should not call this function directly, but instead call RTOutsignal::invoke() because it will provide most of the needed parameters for you. However, if you need to programatically invoke on a general port based on descriptor info this function can be used.

Parameters

replyBuffer	A caller-supplied message object that stores the reply message(s) resulting from the invoke. The caller is responsible for allocating and deleting the message(s) when they are no longer required. To verify that a returned message is valid call RTMessage::isValid() once the invoke returns.
signal	The id of the event to invoke
data	Data object to pass with the invoke
type	Type descriptor describing the data object
implicitReply	Whether it should be allowed for the receiver to not make a reply call if no data needs to be passed back to the sender.

Returns: 1 if the invoke was successful, 0 otherwise.

◆ invokeAt()

int RTProtocol::invokeAt	(	int	index,
		RTMessage *	replyBuffer,
		int	signal,
		const void *	data,
		const RTObject_class *	type,
		bool	implicitReply
	)

Invoke an event on a replicated port at a specified index.

Normally you should not call this function directly, but instead call RTOutsignal::invokeAt() because it will provide most of the needed parameters for you. However, if you need to programatically invoke on a general port based on descriptor info this function can be used.

Parameters

index	The 0-based index of the port instance within the port on which to perform the invoke (0 <= index < size())
replyBuffer	A caller-supplied message object that stores the reply message(s) resulting from the invoke. The caller is responsible for allocating and deleting the message(s) when they are no longer required. To verify that a returned message is valid call RTMessage::isValid() once the invoke returns.
signal	The id of the event to invoke
data	Data object to pass with the invoke
type	Type descriptor describing the data object
implicitReply	Whether it should be allowed for the receiver to not make a reply call if no data needs to be passed back to the sender.

Returns: 1 if the invoke was successful, 0 otherwise.

◆ isBoundAt()

int RTProtocol::isBoundAt ( int index ) const

Determine if a port instance is currently connected to another port instance.

Parameters

index 0-based index of the port instance within the port (0 <= index < size())

Returns: 1 if the port instance at the specified index is connected to another port instance. 0 if it is not connected.

◆ isIndexTo()

int RTProtocol::isIndexTo	(	int	index,
		RTActor *	capsule
	)		const

Determine if a port instance is currently connected to a port instance owned by a certain capsule instance.

Parameters

index	0-based index of the port instance within the port (0 <= index < size())
capsule	Capsule instance

Returns: 1 if the port instance at the specified index is connected to another port instance that is owned by the specified capsule instance. 0 if not.

◆ isRegistered()

int RTProtocol::isRegistered ( void ) const

Determine if the port is currently registered with the layer service or not.

Returns: 1 if the unwired port is currently registered with the layer service, 0 otherwise.

◆ purge()

int RTProtocol::purge ( void )

Empty the defer queue of all port instances without recalling any deferred message.

To delete deferred messages for one port instance only, use purgeAt().

Returns: The number of messages deleted from the defer queue.

◆ purgeAt()

int RTProtocol::purgeAt ( int index )

Empty the defer queue of a specified port instance without recalling any deferred message.

To delete deferred messages for all port instances, use purge().

Returns: The number of messages deleted from the defer queue.

◆ recall()

int RTProtocol::recall ( void )

Recall a message from the defer queue and insert it at the back of the controller's message queue (after other queued messages).

The recalled message can be for any port instance.

Returns: The number of messages recalled from the defer queue (i.e. either 1 or 0).

◆ recallAll()

int RTProtocol::recallAll ( void )

Recall all messages from the defer queue and insert them at the back of the controller's message queue (after other queued messages).

The recalled messages can be for any port instance.

Returns: The number of messages recalled from the defer queue.

◆ recallAllAt()

int RTProtocol::recallAllAt	(	int	index,
		int	front = `0`
	)

Recall all messages from the defer queue and insert them in the controller's message queue.

By default the recalled messages are inserted at the back of the message queue. The recalled messages must be for the port instance at the specified index.

Parameters

index	Index of the port instance for which to recall the messages.
front	Set this parameter to 1 to insert the recalled messages at the front of the message queue instead of at the back which is the default behavior.

Returns: The number of messages recalled from the defer queue.

◆ recallAllFront()

int RTProtocol::recallAllFront ( void )

Recall all messages from the defer queue and insert them at the front of the controller's message queue (before other queued messages).

The recalled messages can be for any port instance.

Returns: The number of messages recalled from the defer queue.

◆ recallAt()

int RTProtocol::recallAt	(	int	index,
		int	front = `0`
	)

Recall a message from the defer queue and insert it in the controller's message queue.

By default the recalled message is inserted at the back of the message queue. The recalled message must be for the port instance at the specified index.

Parameters

index	Index of the port instance for which to recall a message.
front	Set this parameter to 1 to insert the recalled message at the front of the message queue instead of at the back which is the default behavior.

Returns: The number of messages recalled from the defer queue (i.e. either 1 or 0).

◆ recallFront()

int RTProtocol::recallFront ( void )

Recall a message from the defer queue and insert it at the front of the controller's message queue (before other queued messages).

The recalled message can be for any port instance.

Returns: The number of messages recalled from the defer queue (i.e. either 1 or 0).

◆ receiveCheck()

RTProtocolDescriptor::Status RTProtocol::receiveCheck	(	int	signal,
		const RTObject_class *	type
	)		const

Check if a particular event would be possible to receive on this port.

If type checking is disabled no check is performed.

Parameters

signal	The id of the event
type	The type descriptor of the event data, or 0 if the event does not have any data.

Returns: A literal from the RTProtocolDescriptor::Status enum describing if the event could be received on the port or not. "ok" means it would be possible to receive the event. "badSignal" means the event is not an incoming (or outgoing if the port is conjugated) event in the protocol that types the port. "badType" means the type descriptor does not match the type specified for the protocol event.

◆ receiveTypeCheckEnable()

void RTProtocol::receiveTypeCheckEnable ( int on_off )

Turn on or off type checking when receiving an event on the port.

Calling this function has no effect if the macro RTTYPECHECK_SEND has been set to RTTYPECHECK_DONT. Type checking is by default turned on for all ports and can help detect problems during development. However, the application will run slightly faster if you turn it off.

Parameters

on_off Set to 0 to turn off type checking for the port, and 1 (or any non-zero value to turn it on.

◆ receiveTypeCheckEnabled()

int RTProtocol::receiveTypeCheckEnabled ( void ) const

Determine if type checking when receiving events is enabled.

Returns: 1 if type checking on event reception has been turned on for this port, 0 otherwise.

◆ registerAs()

int RTProtocol::registerAs ( const char * service )

Register an unwired port either as an SAP or SPP (depending on the "Publish" property of the port).

Deprecated:: Be specific and use registerSPP() or registerSAP() instead.

Returns: 1 on successful registration, 0 otherwise.

◆ registerSAP()

int RTProtocol::registerSAP ( const char * service )

Register an unwired port (SAP) with the layer service (as a "client").

If this function is invoked on an SAP which is already registered with a different name, then the original registered name is automatically deregistered, and the SAP is registered with the new name. Registering an SAP enables an SPP to later connect to it using the specified service name.

Parameters

service A string that is used to identify a unique service name under which SAPs and SPPs will connect.

Returns: 1 if the registration of the service name was successful, and 0 otherwise. The registration fails if the port is not an unwired port. If the SAP is already registered with this same name, the function returns 1.

◆ registerSPP()

int RTProtocol::registerSPP ( const char * service )

Register an unwired port (SPP) with the layer service (as the "provider").

If this function is invoked on an SAP which is already registered with a different name, then the original registered name is automatically deregistered, and the SAP is registered with the new name. Registering an SPP enables SAPs to later connect to it using the specified service name.

Parameters

service A string that is used to identify a unique service name under which SAPs and SPPs will connect.

Returns: 1 if the registration of the service name was successful, and 0 otherwise. The registration fails if the port is not an unwired port. If the SPP is already registered with this same name, the function returns 1.

◆ reply()

int RTProtocol::reply	(	int	signal,
		const void *	data,
		const RTObject_class *	type
	)

Make a reply to respond to an invoke.

Normally you should not call this function directly, but instead call RTOutsignal::reply() because it will provide all of the needed parameters for you. However, if you need to programatically reply on a general port based on descriptor info this function can be used.

Parameters

signal	The id of the event to reply with
data	Data object to pass with the reply
type	Type descriptor describing the data object

Returns: 1 if the reply was successful, 0 otherwise.

◆ resize()

int RTProtocol::resize ( int new_size )

Set a new size (i.e.

multiplicity) for the port. This can only be done on non-wired ports. Increasing the size gives room for more connections, while decreasing the size may lead to that some established connections will be dropped.

Parameters

new_size New size for the port. Must be >= 0.

Returns: 1 if successful and 0 if resizing fails (use RTActor::getError() then to determine the cause for the failure.

◆ send()

int RTProtocol::send	(	int	signal,
		const void *	data,
		const RTObject_class *	type,
		int	priority,
		bool	moveData = `false`
	)

Send an event on the port.

Normally you should not call this function directly, but instead call RTOutsignal::send() because it will provide most of the needed parameters for you. However, if you need to programatically send on a general port based on descriptor info this function can be used.

Parameters

signal	The id of the event to send
data	Data object to pass with the sent event
type	Type descriptor describing the data object
priority	The priority at which the event should be sent. A message priority is interpreted as its relative importance with respect to all other unprocessed messages on a thread. The priority evaluates to one of the defined global priority values.
moveData	Set to true if you want the data object to be moved instead of copied when sending the event

Returns: 1 if the event was successfully sent, 0 otherwise.

◆ sendAt()

int RTProtocol::sendAt	(	int	index,
		int	signal,
		const void *	data,
		const RTObject_class *	type,
		int	priority,
		bool	moveData = `false`
	)

Send an event on a replicated port at a specified index.

Normally you should not call this function directly, but instead call RTOutsignal::sendAt() because it will provide most of the needed parameters for you. However, if you need to programatically send on a general port based on descriptor info this function can be used.

Parameters

index	The 0-based index of the port instance within the port on which to send the event (0 <= index < size())
signal	The id of the event to send
data	Data object to pass with the sent event
type	Type descriptor describing the data object
priority	The priority at which the event should be sent. A message priority is interpreted as its relative importance with respect to all other unprocessed messages on a thread. The priority evaluates to one of the defined global priority values.
moveData	Set to true if you want the data object to be moved instead of copied when sending the event

Returns: 1 if the event was successfully sent, 0 otherwise.

◆ sendCheck()

RTProtocolDescriptor::Status RTProtocol::sendCheck	(	int	signal,
		const RTObject_class *	type
	)		const

Check if a particular event would be possible to send on this port.

If type checking is disabled no check is performed.

Parameters

signal	The id of the event
type	The type descriptor of the event data, or 0 if the event does not have any data.

Returns: A literal from the RTProtocolDescriptor::Status enum describing if the event could be sent on the port or not. "ok" means it would be possible to send the event. "badSignal" means the event is not an outgoing (or incoming if the port is conjugated) event in the protocol that types the port. "badType" means the type descriptor does not match the type specified for the protocol event.

◆ sendTypeCheckEnable()

void RTProtocol::sendTypeCheckEnable ( int on_off )

Turn on or off type checking when performing send(), invoke() or reply() on the port.

Calling this function has no effect if the macro RTTYPECHECK_SEND has been set to RTTYPECHECK_DONT. Type checking is by default turned on for all ports and can help detect problems during development. However, the application will run slightly faster if you turn it off.

Parameters

on_off Set to 0 to turn off type checking for the port, and 1 (or any non-zero value to turn it on.

◆ sendTypeCheckEnabled()

int RTProtocol::sendTypeCheckEnabled ( void ) const

Determine if type checking when sending events is enabled.

Returns: 1 if type checking when sending events has been turned on for this port, 0 otherwise.

◆ size()

int RTProtocol::size ( void ) const

Get the size of the port.

Returns: The replication factor of the port, i.e. the size as defined by the port multiplicity. This specifies the maximum number of port instances, which is also the maximum number of possible connections to remote port instances.

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

RTProtocol.h
RTProtocol.inl

Public Member Functions

Protected Types

Protected Member Functions

Friends

Detailed Description

Member Function Documentation

◆ bindingNotification()

◆ bindingNotificationRequested()

◆ context()

◆ defaultLayerName()

◆ deregister()

◆ deregisterSAP()

◆ deregisterSPP()

◆ getId()

◆ getInfo()

◆ getName()

◆ getOwner()

◆ getRegisteredName()

◆ indexTo()

◆ invoke()

◆ invokeAt()

◆ isBoundAt()

◆ isIndexTo()

◆ isRegistered()

◆ purge()

◆ purgeAt()

◆ recall()

◆ recallAll()

◆ recallAllAt()

◆ recallAllFront()

◆ recallAt()

◆ recallFront()

◆ receiveCheck()

◆ receiveTypeCheckEnable()

◆ receiveTypeCheckEnabled()

◆ registerAs()

◆ registerSAP()

◆ registerSPP()

◆ reply()

◆ resize()

◆ send()

◆ sendAt()

◆ sendCheck()

◆ sendTypeCheckEnable()

◆ sendTypeCheckEnabled()

◆ size()