RTI Connext C API
Version 5.3.1
|
Built-in transport plug-in for inter-process communications using shared memory (NDDS_TRANSPORT_CLASSID_SHMEM) More...
Data Structures | |
struct | NDDS_Transport_Shmem_Property_t |
Subclass of NDDS_Transport_Property_t allowing specification of parameters that are specific to the shared-memory transport. More... | |
Macros | |
#define | NDDS_TRANSPORT_SHMEM_ADDRESS_BIT_COUNT (0) |
Default value of NDDS_Transport_Property_t::address_bit_count. | |
#define | NDDS_TRANSPORT_SHMEM_PROPERTIES_BITMAP_DEFAULT ( NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED ) |
Default value of NDDS_Transport_Property_t::properties_bitmap. | |
#define | NDDS_TRANSPORT_SHMEM_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT (1024) |
Default value of NDDS_Transport_Property_t::gather_send_buffer_count_max. | |
#define | NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT (65536) |
Default value of NDDS_Transport_Property_t::message_size_max. | |
#define | NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT (64) |
Default value of NDDS_Transport_Shmem_Property_t::received_message_count_max. | |
#define | NDDS_TRANSPORT_SHMEM_RECEIVE_BUFFER_SIZE_DEFAULT |
Default value of NDDS_Transport_Shmem_Property_t::receive_buffer_size. | |
#define | NDDS_TRANSPORT_SHMEM_PROPERTY_DEFAULT |
Use this to initialize stack variable. | |
Functions | |
NDDS_Transport_Plugin * | NDDS_Transport_Shmem_new (const struct NDDS_Transport_Shmem_Property_t *property_in) |
Create a new shmem process transport. | |
NDDS_Transport_Plugin * | NDDS_Transport_Shmem_create (NDDS_Transport_Address_t *default_network_address_out, const struct DDS_PropertyQosPolicy *property_in) |
Create a new shmem process transport, using PropertyQosPolicy. | |
Built-in transport plug-in for inter-process communications using shared memory (NDDS_TRANSPORT_CLASSID_SHMEM)
This plugin uses System Shared Memory to send messages between processes on the same node.
The transport plugin has exactly one "receive interface"; since the address_bit_count
is 0, it can be assigned any address. Thus the interface is located by the "network address" associated with the transport plugin.
Opening a receiver "port" on shared memory corresponds to creating a shared memory segment using a name based on the port number. The transport plugin's properties are embedded in the shared memory segment.
When a sender tries to send to the shared memory port, it verifies that properties of the receiver's shared memory transport are compatible with those specified in its transport plugin. If not, the sender will fail to attach to the port and will output messages such as below (with numbers appropriate to the properties of the transport plugins involved).
NDDS_Transport_Shmem_attachShmem:failed to initialize incompatible properties NDDS_Transport_Shmem_attachShmem:countMax 0 > -19417345 or max size -19416188 > 2147482624
In this scenario, the properties of the sender or receiver transport plugin instances should be adjusted, so that they are compatible.
If a process using shared memory crashes (say because the user typed in ^C), resources associated with its shared memory ports may not be properly cleaned up. Later, if another RTI Connext process needs to open the same ports (say, the crashed program is restarted), it will attempt to reuse the shared memory segment left behind by the crashed process.
The reuse is allowed iff the properties of transport plugin are compatible with those embedded in the shared memory segment (i.e., of the original creator). Otherwise, the process will fail to open the ports, and will output messages such as below (with numbers appropriate to the properties of the transport plugins involved).
NDDS_Transport_Shmem_create_recvresource_rrEA:failed to initialize shared memory resource Cannot recycle existing shmem: size not compatible for key 0x1234
In this scenario, the shared memory segments must be cleaned up using appropriate platform specific commands. For details, please refer to the Platform Notes.
The transport uses the shared memory segment keys, given by the formula below.
The transport also uses signaling shared semaphore keys given by the formula below.
The transport also uses mutex shared semaphore keys given by the formula below.
wher the port
is a function of the domain_id
and the participant_id
, as described in DDS_WireProtocolQosPolicy::participant_id
RTI Connext can implicitly create this plugin and register with the DDS_DomainParticipant if this transport is specified in DDS_TransportBuiltinQosPolicy.
To specify the properties of the builtin shared memory transport that is implicitly registered, you can either:
Builtin transport plugin properties specified in DDS_PropertyQosPolicy always overwrite the ones specified through NDDS_Transport_Support_set_builtin_transport_property(). The default value is assumed on any unspecified property. Note that all properties should be set before the transport is implicitly created and registered by RTI Connext. See Built-in Transport Plugins for details on when a builtin transport is registered.
To explicitly create an instance of this plugin, NDDS_Transport_Shmem_new() should be called. The instance should be registered with RTI Connext, see NDDS_Transport_Support_register_transport. In some configurations, you may have to disable the builtin shared memory transport plugin instance (DDS_TransportBuiltinQosPolicy, DDS_TRANSPORTBUILTIN_SHMEM), to avoid port conflicts with the newly created plugin instance.
The following table lists the predefined property names that can be set in the DDS_PropertyQosPolicy of a DDS_DomainParticipant to configure the builtin shared memory transport plugin.
Name | Descriptions |
---|---|
dds.transport.shmem.builtin.parent.address_bit_count | See NDDS_Transport_Property_t::address_bit_count |
dds.transport.shmem.builtin.parent.properties_bitmap | See NDDS_Transport_Property_t::properties_bitmap |
dds.transport.shmem.builtin.parent.gather_send_buffer_count_max | See NDDS_Transport_Property_t::gather_send_buffer_count_max |
dds.transport.shmem.builtin.parent.message_size_max | See NDDS_Transport_Property_t::message_size_max |
dds.transport.shmem.builtin.parent.allow_interfaces | See NDDS_Transport_Property_t::allow_interfaces_list and NDDS_Transport_Property_t::allow_interfaces_list_length. Interfaces should be specified as comma-separated strings, with each comma delimiting an interface. For example: 127.0.0.1,eth0 |
dds.transport.shmem.builtin.parent.deny_interfaces | See NDDS_Transport_Property_t::deny_interfaces_list and NDDS_Transport_Property_t::deny_interfaces_list_length. Interfaces should be specified as comma-separated strings, with each comma delimiting an interface. For example: 127.0.0.1,eth0 |
dds.transport.shmem.builtin.parent.allow_multicast_interfaces | See NDDS_Transport_Property_t::allow_multicast_interfaces_list and NDDS_Transport_Property_t::allow_multicast_interfaces_list_length. Interfaces should be specified as comma-separated strings, with each comma delimiting an interface. For example: 127.0.0.1,eth0 |
dds.transport.shmem.builtin.parent.deny_multicast_interfaces | See NDDS_Transport_Property_t::deny_multicast_interfaces_list and NDDS_Transport_Property_t::deny_multicast_interfaces_list_length. Interfaces should be specified as comma-separated strings, with each comma delimiting an interface. For example: 127.0.0.1,eth0 |
dds.transport.shmem.builtin.received_message_count_max | See NDDS_Transport_Shmem_Property_t::received_message_count_max |
dds.transport.shmem.builtin.receive_buffer_size |
#define NDDS_TRANSPORT_SHMEM_ADDRESS_BIT_COUNT (0) |
Default value of NDDS_Transport_Property_t::address_bit_count.
#define NDDS_TRANSPORT_SHMEM_PROPERTIES_BITMAP_DEFAULT ( NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED ) |
Default value of NDDS_Transport_Property_t::properties_bitmap.
#define NDDS_TRANSPORT_SHMEM_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT (1024) |
Default value of NDDS_Transport_Property_t::gather_send_buffer_count_max.
#define NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT (65536) |
Default value of NDDS_Transport_Property_t::message_size_max.
#define NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT (64) |
Default value of NDDS_Transport_Shmem_Property_t::received_message_count_max.
#define NDDS_TRANSPORT_SHMEM_RECEIVE_BUFFER_SIZE_DEFAULT |
Default value of NDDS_Transport_Shmem_Property_t::receive_buffer_size.
#define NDDS_TRANSPORT_SHMEM_PROPERTY_DEFAULT |
Use this to initialize stack variable.
NDDS_Transport_Plugin* NDDS_Transport_Shmem_new | ( | const struct NDDS_Transport_Shmem_Property_t * | property_in | ) |
Create a new shmem process transport.
An application may create multiple transports, possibly for use in different domains.
property_in | <<in>> Desired behavior of this transport. May be NULL for default property. The transport plugin can only support one unicast receive interface; therefore the interface selection lists are ignored. |
NDDS_Transport_Plugin* NDDS_Transport_Shmem_create | ( | NDDS_Transport_Address_t * | default_network_address_out, |
const struct DDS_PropertyQosPolicy * | property_in | ||
) |
Create a new shmem process transport, using PropertyQosPolicy.
An application may create multiple transports, possibly for use in different domains.
default_network_address_out | <<out>> Network address to be used when registering the transport. |
property_in | <<in>> Desired behavior of this transport. May be NULL for default property. The transport plugin can only support one unicast receive interface; therefore the interface selection lists are ignored. |