Publish Subscribe Message Exchange¶

group psmx

The Publish Subscribe Message Exchange (PSMX) interface allows implementing additional methods of pub-sub data-exchange as an alternative to Cyclone’s networked transport. The PSMX interface allows to load implementations as plugins, so there is no need for compile-time linking.

Typedefs

typedef enum dds_psmx_endpoint_type dds_psmx_endpoint_type_t¶: Type of the PSMX endpoint.

typedef uint32_t dds_psmx_instance_id_t¶: Identifier for the PSMX instance.

typedef struct dds_psmx_metadata dds_psmx_metadata_t¶: describes the data which is transferred in addition to just the sample

typedef struct dds_psmx_node_identifier dds_psmx_node_identifier_t¶: identifier used to distinguish between PSMX instances on nodes

typedef bool (*dds_psmx_type_qos_supported_fn)(struct dds_psmx *psmx_instance, dds_psmx_endpoint_type_t forwhat, dds_data_type_properties_t data_type_props, const struct dds_qos *qos)¶

Definition for function that checks QoS support.

Definition for function that checks whether the provided QoS is supported by the PSMX implementation.

Param psmx_instance: [in] The PSMX instance.
Param forwhat: [in] whether for a topic/writer/reader (UNSET if topic)
Param data_type_props: [in] Data type properties
Param qos: [in] The QoS.
Return: true if the QoS is supported, false otherwise

typedef struct dds_psmx_topic *(*dds_psmx_create_topic_fn)(struct dds_psmx *psmx_instance, const char *topic_name, const char *type_name, dds_data_type_properties_t data_type_props)¶

Definition for function to create a topic

Definition for a function that is called to create a new topic for a PSMX instance.

Param psmx_instance: [in] The PSMX instance.
Param topic_name: [in] The name of the topic to create
Param type_name: [in] The name of the DDS data type for this topic
Param data_type_props: [in] The data type properties for the topic’s data type.
Return: a PSMX topic structure

typedef dds_return_t (*dds_psmx_delete_topic_fn)(struct dds_psmx_topic *psmx_topic)¶

Definition for function to destruct a topic

Definition for a function that is called on topic destruction.

Param psmx_topic: [in] The PSMX topic to destruct
Return: a DDS return code

typedef dds_return_t (*dds_psmx_deinit_fn)(struct dds_psmx *psmx_instance)¶

Function definition for pubsub message exchange cleanup.

Param psmx_instance: [in] the psmx instance to de-initialize
Return: a DDS return code

typedef dds_psmx_node_identifier_t (*dds_psmx_get_node_identifier_fn)(const struct dds_psmx *psmx_instance)¶

Definition for PSMX locator generation function

Returns a locator which is unique between nodes, but identical for instances on the same node.

Param psmx_instance: [in] a PSMX instance
Return: a unique node identifier (locator)

typedef dds_psmx_features_t (*dds_psmx_supported_features_fn)(const struct dds_psmx *psmx_instance)¶

Definition for PSMX function to get supported features

Returns an integer with the flags set for the features that are supported by the provided PSMX instance.

Param psmx_instance: [in] a PSMX instance
Return: the set of features supported by this PSMX instance

typedef struct dds_psmx_ops dds_psmx_ops_t¶: functions which are used on a PSMX instance

typedef struct dds_psmx_endpoint *(*dds_psmx_create_endpoint_fn)(struct dds_psmx_topic *psmx_topic, const struct dds_qos *qos, dds_psmx_endpoint_type_t endpoint_type)¶

Definition of function to create an endpoint for a topic.

Param psmx_topic: [in] The PSMX topic to create the endpoint for
Param endpoint_type: [in] The type of endpoint to create (publisher or subscriber)
Return: A PSMX endpoint struct

typedef dds_return_t (*dds_psmx_delete_endpoint_fn)(struct dds_psmx_endpoint *psmx_endpoint)¶

Definition of function to delete an PSMX endpoint.

Param psmx_endpoint: [in] The endpoint to be deleted
Return: a DDS return code

typedef struct dds_psmx_topic_ops dds_psmx_topic_ops_t¶: functions which are used on a PSMX topic

typedef dds_loaned_sample_t *(*dds_psmx_endpoint_request_loan_fn)(struct dds_psmx_endpoint *psmx_endpoint, uint32_t size_requested)¶

Definition for function to requests a loan from the PSMX.

Param psmx_endpoint: [in] the endpoint to loan from
Param size_requested: [in] the size of the loan requested
Return: a pointer to the loaned block on success

typedef dds_return_t (*dds_psmx_endpoint_write_fn)(struct dds_psmx_endpoint *psmx_endpoint, dds_loaned_sample_t *data)¶

Definition of function to write data on a PSMX endpoint.

Param psmx_endpoint: [in] The endpoint to publish the data on
Param data: [in] The data to publish
Return: a DDS return code

typedef dds_loaned_sample_t *(*dds_psmx_endpoint_take_fn)(struct dds_psmx_endpoint *psmx_endpoint)¶

Definition of function to take data from an PSMX endpoint.

Used in a poll based implementation.

Param psmx_endpoint: [in] The endpoint to take the data from
Return: the oldest unread received block of memory

typedef dds_return_t (*dds_psmx_endpoint_on_data_available_fn)(struct dds_psmx_endpoint *psmx_endpoint, dds_entity_t reader)¶

Definition of function to set the a callback function on an PSMX endpoint.

Param psmx_endpoint: [in] the endpoint to set the callback function on
Param reader: [in] the DDS reader associated with the endpoint
Return: a DDS return code

typedef struct dds_psmx_endpoint_ops dds_psmx_endpoint_ops_t¶: Functions that are used on a PSMX endpoint.

typedef struct dds_psmx dds_psmx_t¶: the top-level entry point on the PSMX is bound to a specific implementation of a PSMX

typedef struct dds_psmx_topic dds_psmx_topic_t¶

the topic-level PSMX

this will exchange data for readers and writers which are matched through discovery will only exchange a single type of data

typedef struct dds_psmx_endpoint dds_psmx_endpoint_t¶: the definition of one instance of a dds reader/writer using a PSMX instance

Enums

enum dds_psmx_endpoint_type¶

Type of the PSMX endpoint.

Values:

enumerator DDS_PSMX_ENDPOINT_TYPE_UNSET¶

enumerator DDS_PSMX_ENDPOINT_TYPE_READER¶

enumerator DDS_PSMX_ENDPOINT_TYPE_WRITER¶

Functions

dds_return_t dds_add_psmx_topic_to_list(struct dds_psmx_topic *psmx_topic, struct dds_psmx_topic_list_elem **list)¶

adds a topic to the list

will create the first list entry if it does not yet exist

Parameters

psmx_topic – [in] the topic to add
list – [inout] list to add the topic to

Returns

DDS_RETCODE_OK on success

dds_return_t dds_remove_psmx_topic_from_list(struct dds_psmx_topic *psmx_topic, struct dds_psmx_topic_list_elem **list)¶

removes a topic from the list

will set the pointer to the list to null if the last entry is removed

Parameters

psmx_topic – [in] the topic to remove
list – [inout] list to remove the topic from

Returns

a DDS return code

dds_return_t dds_add_psmx_endpoint_to_list(struct dds_psmx_endpoint *psmx_endpoint, struct dds_psmx_endpoint_list_elem **list)¶

adds an endpoint to the list

will create the first list entry if it does not yet exist

Parameters

psmx_endpoint – [in] the endpoint to add
list – [inout] list to add the endpoint to

Returns

a DDS return code

dds_return_t dds_remove_psmx_endpoint_from_list(struct dds_psmx_endpoint *psmx_endpoint, struct dds_psmx_endpoint_list_elem **list)¶

removes an endpoint from the list

will set the pointer to the list to null if the last entry is removed

Parameters

psmx_endpoint – [in] the endpoint to remove
list – [inout] list to remove the endpoint from

Returns

a DDS return code

dds_return_t dds_psmx_init_generic(struct dds_psmx *psmx)¶

initialization function for PSMX instance

Should be called from all constructors of class which inherit from dds_psmx_t

Parameters

psmx – [in] the PSMX instance to initialize

Returns

a DDS return code

dds_return_t dds_psmx_cleanup_generic(struct dds_psmx *psmx)¶

cleanup function for a PSMX instance

Should be called from all destructors of classes which inherit from dds_psmx_t

Parameters

psmx – [in] the PSMX instance to cleanup

Returns

a DDS return code

dds_return_t dds_psmx_topic_init_generic(struct dds_psmx_topic *psmx_topic, const dds_psmx_topic_ops_t *ops, const struct dds_psmx *psmx, const char *topic_name, const char *type_name, dds_data_type_properties_t data_type_props)¶

init function for topic

Should be called from all constructors of classes which inherit from struct dds_psmx_topic

Parameters

psmx_topic – [in] the topic to initialize
ops – [in] vtable for this psmx_topic
psmx – [in] the PSMX instance
topic_name – [in] the topic name
type_name – [in] the DDS type name for this topic
data_type_props – [in] the data type’s properties

Returns

a DDS return code

dds_return_t dds_psmx_topic_cleanup_generic(struct dds_psmx_topic *psmx_topic)¶

cleanup function for a topic

Should be called from all destructors of classes which inherit from struct dds_psmx_topic

Parameters

psmx_topic – [in] the topic to de-initialize

Returns

a DDS return code

dds_psmx_features_t dds_psmx_supported_features(const struct dds_psmx *psmx_instance)¶

Gets the supported features for a PSMX instance.

Returns the set of supported features for the provided PSMX instance.

Parameters

psmx_instance – [in] the PSMX instance

Returns

the set of features supported by this PSMX instance

struct dds_psmx_metadata¶: #include <dds_psmx.h>

describes the data which is transferred in addition to just the sample

struct dds_psmx_node_identifier¶: #include <dds_psmx.h>

identifier used to distinguish between PSMX instances on nodes

struct dds_psmx_ops¶: #include <dds_psmx.h>

functions which are used on a PSMX instance

struct dds_psmx_topic_ops¶: #include <dds_psmx.h>

functions which are used on a PSMX topic

struct dds_psmx_endpoint_ops¶: #include <dds_psmx.h>

Functions that are used on a PSMX endpoint.

struct dds_psmx¶

#include <dds_psmx.h>

the top-level entry point on the PSMX is bound to a specific implementation of a PSMX

Public Members

dds_psmx_ops_t ops¶: associated functions

const char *instance_name¶: name of this PSMX instance

int32_t priority¶: priority of choosing this interface

const struct ddsi_locator *locator¶: the locator for this PSMX instance

dds_psmx_instance_id_t instance_id¶: the identifier of this PSMX instance

struct dds_psmx_topic_list_elem *psmx_topics¶: associated topics

struct dds_psmx_topic¶

#include <dds_psmx.h>

the topic-level PSMX

this will exchange data for readers and writers which are matched through discovery will only exchange a single type of data

Public Members

dds_psmx_topic_ops_t ops¶: associated functions

struct dds_psmx *psmx_instance¶: the PSMX instance which created this topic

char *topic_name¶: the topic name

char *type_name¶: the type name

dds_loan_data_type_t data_type¶: the unique identifier associated with the data type of this topic

struct dds_psmx_endpoint_list_elem *psmx_endpoints¶: associated endpoints

dds_data_type_properties_t data_type_props¶: the properties of the datatype associated with this topic

struct dds_psmx_endpoint¶

#include <dds_psmx.h>

the definition of one instance of a dds reader/writer using a PSMX instance

Public Members

dds_psmx_endpoint_ops_t ops¶: associated functions

struct dds_psmx_topic *psmx_topic¶: the topic this endpoint belongs to

dds_psmx_endpoint_type_t endpoint_type¶: type type of endpoint