4. Loading a Connector¶

4.1. Importing the Connector package¶

To use the rticonnextdds_connector package, import it. For example:

import rticonnextdds_connector as rti

4.2. Creating a new Connector¶

To create a new Connector, pass an XML file and a configuration name:

connector = rti.Connector("MyParticipantLibrary::MyParticipant", "ShapeExample.xml");

The XML file defines your types, QoS profiles, and DDS Entities. Connector uses the XML schema of RTI’s XML-Based Application Creation.

The previous code loads the <domain_participant> named MyParticipant in the <domain_participant_library> named MyParticipantLibrary, which is defined in the file ShapeExample.xml:

<domain_participant_library name="MyParticipantLibrary">
  <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
    ...
  </domain_participant>
</domain_participant_library>

See the full file here: ShapeExample.xml.

When you create a Connector, the DDS DomainParticipant that you selected and all its contained entities (Topics, Subscribers, DataReaders, Publishers, DataWriters) are created.

For more information about the DDS entities, see Core Concepts in the RTI Connext DDS Core Libraries User’s Manual.

Note

Operations on the same Connector instance or its contained entities are not protected for multi-threaded access. See Threading model for more information.

4.3. Closing a Connector¶

To destroy all the DDS entities that belong to a previously created Connector, call Connector.close():

connector = rti.Connector("MyParticipantLibrary::MyParticipant", "ShapeExample.xml")
# ...
connector.close()

Alternatively, you can use the open_connector() resource manager to open and automatically close the connector:

with rti.open_connector("MyParticipantLibrary::MyParticipant", "ShapeExample.xml") as connector:
   # Use connector
   input = connector.get_input("MySubscriber::MySquareReader")
   # ...

4.4. Getting the Inputs and Outputs¶

Once you have created a Connector instance, Connector.get_output() returns the Output that allows writing data, and Connector.get_input() returns the Input that allows reading data.

Note

If the <domain_participant> you load contains both <data_writer> (Output) and <data_reader> (Input) tags for the same Topic and they have matching QoS, when you write data, the Inputs will receive the data even before you call Connector.get_input(). To avoid that, you can configure the <subscriber> that contains the <data_reader> with <subscriber_qos>/<entity_factory>/<autoenable_created_entities> set to false. Then the Inputs will only receive data after you call Connector.get_input().

For more information see:

Writing Data (Output)

Reading Data (Input)

4.5. Class reference: Connector¶

class rticonnextdds_connector.Connector(config_name, url)¶

Loads a configuration and creates its Inputs and Outputs

A Connector instance loads a configuration from an XML document. For example:

connector = rti.Connector("MyParticipantLibrary::MyParticipant", "MyExample.xml")

After creating it, the Connector’s Inputs can be used to read data, and the Outputs to write. See get_input() and get_output().

An application can create multiple Connector instances for the same or different configurations.

A Connector instance must be deleted with close().

Parameters:

config_name (str) – The configuration to load. The config_name format is "LibraryName::ParticipantName", where LibraryName is the name attribute of a <domain_participant_library> tag, and ParticipantName is the name attribute of a <domain_participant> tag inside the library.
url (str) – An URL locating the XML document. The url can be a file path (for example, '/tmp/my_dds_config.xml'), a string containing the full XML document with the following format 'str://"<dds>...</dds>"'), or a combination of multiple files or strings, as explained in the URL Groups section of the Connext DDS Core Libraries User’s Manual.

close()¶: Frees all the resources created by this Connector instance

get_input(input_name)¶

Returns the Input named input_name

input_name identifies a <data_reader> tag in the configuration loaded by this Connector. For example, the following code:

connector = rti.Connector("MyParticipantLibrary::MyParticipant", "MyExample.xml")
connector.get_input("MySubscriber::MyReader")

Loads the Output in this example XML:

<domain_participant_library name="MyParticipantLibrary">
  <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
      <subscriber name="MySubscriber">
        <data_reader name="MyReader" topic_ref="MyTopic"/>
        ...
      </subscriber>
      ...
  </domain_participant>
  ...
<domain_participant_library>

Parameters:	input_name (str) – The name of a the `data_reader` to load, with the format `"SubscriberName::DataReaderName"`.
Returns:	The Input if it exists, or else it raises `ValueError`.
Return type:	`Input`

get_output(output_name)¶

Returns the Output named output_name

output_name identifies a <data_writer> tag in the configuration loaded by this Connector. For example, the following code:

connector = rti.Connector("MyParticipantLibrary::MyParticipant", "MyExample.xml")
connector.get_output("MyPublisher::MyWriter")

Loads the Output in this example XML:

<domain_participant_library name="MyParticipantLibrary">
  <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
      <publisher name="MyPublisher">
        <data_writer name="MyWriter" topic_ref="MyTopic"/>
        ...
      </publisher>
      ...
  </domain_participant>
  ...
<domain_participant_library>

Parameters:	output_name (str) – The name of a the `data_writer` to load, with the format `"PublisherName::DataWriterName"`.
Returns:	The Output if it exists, or else it raises `ValueError`.
Return type:	`Output`

static get_version()¶

Returns the version of Connector.

This method provides the build IDs of the native libraries being used by Connector, as well as the version of the Connector API.

Note that if Connector has not been installed via pip, the version of the Connector API being used will be “unknown”. The version of the native libraries will still be returned correctly.

Returns:	A string containing information about the version of Connector.
Return type:	string

static set_max_objects_per_thread()¶

Allows increasing the number of Connector instances that can be created

The default value is 2048. If your application creates more than fifteen Connector instances approximately, you may have to increase this value.

This operation can only be called before creating any Connector instance.

See SYSTEM_RESOURCE_LIMITS QoS Policy in the RTI Connext DDS User’s Manual.

Parameters:	value (number) – The value for max_objects_per_thread

wait(timeout=None)¶

Waits for data to be received on any input

If the operation times out, it raises TimeoutError.

Parameters:	timeout (number) – The maximum to wait in milliseconds. By default, infinite.

rticonnextdds_connector.open_connector(config_name, url)¶

A resource manager that creates and deletes a Connector

It takes the sames arguments as the Connector class:

with rti.open_connector("MyParticipantLibrary::MyParticipant","./ShapeExample.xml") as connector:
    input = connector.get_input("SubscriberName::DataReaderName")
    # ...
# connector closed after with block exits