Represents a port through which an external thread can safely communicate with its owner capsule. More...

#include <RTExternal.h>

Inheritance diagram for External::Base:

Public Types
enum	{ rti_event = rtiLast_RTProtocol + 1 }

Public Member Functions
void	enable (void)
	Enable the owner capsule to receive an event on the external port.

void	disable (void)
	Disable the owner capsule from receiving an event on the external port.

int	raise (const void data=nullptr, const RTObject_class type=nullptr)
	Send an event on the external port.

void	dataPushBack (void *data)
	Store a data object on the external port.

unsigned int	dataPopFront (void **data)
	Pop the first data object off the list of objects stored on the external port.

unsigned int	dataPopBack (void **data)
	Pop the last data object off the list of objects stored on the external port.

void	dataDelete (void *data)
	Attempt to find a specific data object in the list of objects stored on the external port.

RTInSignal	event (void)
	Return the object that represents the event which can be sent to the external port by an external thread, and received by the thread on which the owner capsule executes.

Public Member Functions inherited from RTProtocol
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.

Static Public Attributes
static const RTProtocolDescriptor	rt_class

Protected Types
enum	{ rtiLast_External = rti_event }

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

enum	{ rtiLast_RTProtocol = 0 }

Additional Inherited Members
Protected Member Functions inherited from RTProtocol
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 *)

Detailed Description

Represents a port through which an external thread can safely communicate with its owner capsule.

Member Function Documentation

◆ dataDelete()

void External::Base::dataDelete ( void * data )

Attempt to find a specific data object in the list of objects stored on the external port.

If it is found it will be deleted. This function will typically be called from the same external thread that pushed the object into the list, and it can be useful if the object contains data that has become invalid so that it no longer should be processed by the owner capsule.

Parameters

[in] data Data object to delete.

◆ dataPopBack()

unsigned int External::Base::dataPopBack ( void ** data )

Pop the last data object off the list of objects stored on the external port.

This function should normally be called by the thread on which the owner capsule executes. It is the responsibility of the caller to delete the popped data object when done with it.

Parameters

[out] data The address where to store the retrieved object. Will be null in case of errors (for example when attempting to pop from an empty list).

Returns: The number of data objects remaining in the list of objects stored on the external port.

◆ dataPopFront()

unsigned int External::Base::dataPopFront ( void ** data )

Pop the first data object off the list of objects stored on the external port.

This function should normally be called by the thread on which the owner capsule executes. It is the responsibility of the caller to delete the popped data object when done with it.

Parameters

[out] data The address where to store the retrieved object. Will be null in case of errors (for example when attempting to pop from an empty list).

Returns: The number of data objects remaining in the list of objects stored on the external port.

◆ dataPushBack()

void External::Base::dataPushBack ( void * data )

Store a data object on the external port.

The data object will be put as the last object in the list of objects stored on the external port. This function should normally be called from an external thread when it has data that should be passed to a capsule thread, and when it's not appropriate to pass the data in the call of raise(), for example to avoid copying the data object.

Parameters

[in] data Data object (non-null and dynamically allocated by code in the external thread, which calls this function)

◆ disable()

void External::Base::disable ( void )

Disable the owner capsule from receiving an event on the external port.

This function may only be called from the thread on which the owner capsule executes.

◆ enable()

void External::Base::enable ( void )

Enable the owner capsule to receive an event on the external port.

This function may only be called from the thread on which the owner capsule executes.

◆ raise()

int External::Base::raise	(	const void *	data = `nullptr`,
		const RTObject_class *	type = `nullptr`
	)

Send an event on the external port.

Data can optionally be included in the event. This function may be used only on external threads (i.e. another thread than the one on which the owner capsule executes). Sending of the event will only be successful if the external port is currently enabled for event reception. After this function has been called, the port is automatically disabled from receiving another event until enable() has been called again.

Parameters

[in]	data	Data object to put in the sent event. The data is copied by the TargetRTS using the copy function of the type descriptor.
[in]	type	Type descriptor for the data object.

Returns: 1 on success and 0 if the event could not be sent on the external port (typically because it was not enabled).

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

RTExternal.h
RTExternal.inl

Public Types

Public Member Functions

Static Public Attributes

Protected Types

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ dataDelete()

◆ dataPopBack()

◆ dataPopFront()

◆ dataPushBack()

◆ disable()

◆ enable()

◆ raise()