Built-in transport plug-in for inter-process communications using shared memory. More...

Inheritance diagram for ShmemTransport:

Classes
class	Property_t
	Subclass of com.rti.ndds.transport.Transport.Property_t allowing specification of parameters that are specific to the shared-memory transport. More...

Static Public Attributes
static final int	MESSAGE_SIZE_MAX_DEFAULT
	[default] Value for com.rti.ndds.transport.Transport.Property_t.message_size_max.

static final int	RECEIVED_MESSAGE_COUNT_MAX_DEFAULT
	[default] Value for com.rti.ndds.transport.ShmemTransport.Property_t.received_message_count_max.

static final int	RECEIVE_BUFFER_SIZE_DEFAULT
	[default] Value for com.rti.ndds.transport.ShmemTransport.Property_t.receive_buffer_size.

Detailed Description

Built-in transport plug-in for inter-process communications using shared memory.

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.

Compatibility of Sender and Receiver Transports

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.

Crashing and Restarting Programs

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.

Shared Resource Keys

The transport uses the shared memory segment keys, given by the formula below.

0x400000 + port

The transport also uses signaling shared semaphore keys given by the formula below.

0x800000 + port

The transport also uses mutex shared semaphore keys given by the formula below.

0xb00000 + port

wher the port is a function of the domain_id and the participant_id, as described in com.rti.dds.infrastructure.WireProtocolQosPolicy.participant_id

See Also: com.rti.dds.infrastructure.WireProtocolQosPolicy.participant_id; com.rti.ndds.transport.TransportSupport.set_builtin_transport_property()

Creating and Registering Shared Memory Transport Plugin

RTI Connext can implicitly create this plugin and register with the com.rti.dds.domain.DomainParticipant if this transport is specified in com.rti.dds.infrastructure.TransportBuiltinQosPolicy.

To specify the properties of the builtin shared memory transport that is implicitly registered, you can either:

call com.rti.ndds.transport.TransportSupport.set_builtin_transport_property or
specify the pre-defined property names in com.rti.dds.infrastructure.PropertyQosPolicy associated with the com.rti.dds.domain.DomainParticipant. (see Shared Memory Transport Property Names in Property QoS Policy of Domain Participant).

Builtin transport plugin properties specified in com.rti.dds.infrastructure.PropertyQosPolicy always overwrite the ones specified through com.rti.ndds.transport.TransportSupport.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.

Shared Memory Transport Property Names in Property QoS Policy of Domain Participant

The following table lists the predefined property names that can be set in the com.rti.dds.infrastructure.PropertyQosPolicy of a com.rti.dds.domain.DomainParticipant to configure the builtin shared memory transport plugin.

*Property Strings for Shared Memory Transport*
Name	Descriptions
dds.transport.shmem.builtin.parent.address_bit_count	See com.rti.ndds.transport.Transport.Property_t.address_bit_count
dds.transport.shmem.builtin.parent.properties_bitmap	See com.rti.ndds.transport.Transport.Property_t.properties_bitmap
dds.transport.shmem.builtin.parent.gather_send_buffer_count_max	See com.rti.ndds.transport.Transport.Property_t.gather_send_buffer_count_max
dds.transport.shmem.builtin.parent.message_size_max	See com.rti.ndds.transport.Transport.Property_t.message_size_max
dds.transport.shmem.builtin.parent.allow_interfaces	See com.rti.ndds.transport.Transport.Property_t.allow_interfaces_list and com.rti.ndds.transport.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 com.rti.ndds.transport.Transport.Property_t.deny_interfaces_list and com.rti.ndds.transport.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 com.rti.ndds.transport.Transport.Property_t.allow_multicast_interfaces_list and com.rti.ndds.transport.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 com.rti.ndds.transport.Transport.Property_t.deny_multicast_interfaces_list and com.rti.ndds.transport.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 com.rti.ndds.transport.ShmemTransport.Property_t.received_message_count_max
dds.transport.shmem.builtin.receive_buffer_size	See com.rti.ndds.transport.ShmemTransport.Property_t.receive_buffer_size
dds.transport.shmem.builtin.enable_udp_debugging	See com.rti.ndds.transport.ShmemTransport.Property_t.enable_udp_debugging
dds.transport.shmem.builtin.udp_debugging_address	See com.rti.ndds.transport.ShmemTransport.Property_t.udp_debugging_address
dds.transport.shmem.builtin.udp_debugging_port	See com.rti.ndds.transport.ShmemTransport.Property_t.udp_debugging_port