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:
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. Seeget_input()
andget_output()
.An application can create multiple
Connector
instances for the same or different configurations.A
Connector
instance must be deleted withclose()
.Parameters: - config_name (str) – The configuration to load. The
config_name
format is"LibraryName::ParticipantName"
, whereLibraryName
is thename
attribute of a<domain_participant_library>
tag, andParticipantName
is thename
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
namedinput_name
input_name
identifies a<data_reader>
tag in the configuration loaded by thisConnector
. 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
namedoutput_name
output_name
identifies a<data_writer>
tag in the configuration loaded by thisConnector
. 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
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.
- config_name (str) – The configuration to load. The
-
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