5. Writing Data (Output)¶
5.1. Getting the Output¶
To write a data sample, first look up an Output
:
output = connector.get_output("MyPublisher::MySquareWriter")
Connector.get_output()
returns an Output
object. This example
obtains the output defined by the <data_writer>
named MySquareWriter within
the <publisher>
named MyPublisher:
<publisher name="MyPublisher">
<data_writer name="MySquareWriter" topic_ref="Square" />
</publisher>
This <publisher>
is defined inside the <domain_participant>
selected to create
this connector
(see Creating a new Connector).
5.2. Populating the data sample¶
Then set the output.instance
fields. You can set them member by member:
output.instance.set_number("x", 1)
output.instance.set_number("y", 2)
output.instance.set_number("shapesize", 30)
output.instance.set_string("color", "BLUE")
Or using a dictionary:
output.instance.set_dictionary({"x":1, "y":2, "shapesize":30, "color":"BLUE"})
The name of each member corresponds to the type assigned to this output in XML. For example:
<struct name="ShapeType">
<member name="color" type="string" stringMaxLength="128" key="true" default="RED"/>
<member name="x" type="long" />
<member name="y" type="long" />
<member name="shapesize" type="long" default="30"/>
</struct>
See Instance
and Accessing the data for more information.
5.3. Writing the data sample¶
To write the values you set in output.instance
, call Output.write()
:
output.write()
If the <datawriter_qos>
is set up for reliable communication, you can use
Output.wait()
to block until all matching reliable Subscribers
acknowledge reception of the data sample:
output.wait()
The write method can receive several options. For example, to write with a specific timestamp:
output.write(source_timestamp=100000)
It is also possible to dispose or unregister an instance:
output.write(action="dispose")
output.write(action="unregister")
In these two cases, only the key fields in the output.instance
are relevant
when determining the instance that is disposed or unregistered.
See Output.write()
for more information on the supported parameters.
5.4. Matching with a subscription¶
Before writing, you can use the method Output.wait_for_subscriptions()
to
detect when a compatible DDS subscription is matched or stops matching. It returns
the change in the number of matched subscriptions since the last time it was called:
change_in_matches = output.wait_for_subscriptions()
For example, if a new compatible subscription is discovered within the specified
timeout
, the function returns 1; if a previously matching subscription
no longer matches (for example, due to the application being closed), it returns -1.
You can obtain information about the currently matched subscriptions with
Output.matched_subscriptions
:
matched_subs = output.matched_subscriptions
for sub_info in matched_subs:
sub_name = sub_info['name']
5.5. Class reference: Output, Instance¶
5.5.1. Output class¶
-
class
rticonnextdds_connector.
Output
(connector, name)¶ Allows writting data for a DDS Topic
- Attributes:
See Writing Data (Output).
-
clear_members
()¶ Resets the values of the members of this
Output.instance
If the member is defined with the
default
attribute in the configuration file, it gets that value. Otherwise numbers are set to 0, and strings are set to empty. Sequences are cleared. Optional members are set toNone
.For example, if this
Output
’s type is ShapeType (from the previous example), thenclear_members()
sets color to “RED”, shapesize to 30, and x and y to 0.
-
matched_subscriptions
¶ Returns information about the matched subscriptions
This property returns a list where each element is a dictionary with information about a subscription matched with this Output.
Currently, the only key in the dictionaries is
"name"
, containing the subscription name. If a subscription doesn’t have name, the value isNone
.Note that Connector Inputs are automatically assigned a name from the data_reader name in the XML configuration.
-
wait
(timeout=None)¶ Waits until all matching reliable subscriptions have acknowledged all the samples that have been currently written.
This method only waits if this output is configured with a reliable datawriter_qos.
If the operation times out, it raises
TimeoutError
.Parameters: timeout (number) – The maximum time to wait in milliseconds. By default, infinite.
-
wait_for_subscriptions
(timeout=None)¶ Waits until the number of matched DDS subscription changes
This method waits until new compatible subscriptions are discovered or existing subscriptions no longer match.
Parameters: timeout (number) – The maximum time to wait in milliseconds. By default, infinite. Returns: The change in the current number of matched outputs. If a positive number is returned, the input has matched with new publishers. If a negative number is returned the input has unmatched from an output. It is possible for multiple matches and/or unmatches to be returned (e.g., 0 could be returned, indicating that the input matched the same number of writers as it unmatched). This method raises
TimeoutError
if thetimeout
elapses.
-
write
(**kwargs)¶ Publishes the values of the current
instance
Note that after writing it,
instance
’s values remain unchanged. If for the next write you need to start from scratch, useclear_members()
This method can also dispose or unregister an instance by passing the argument
action="dispose"
oraction="unregister"
. In these two cases, only theinstance
key members are required.This method receives a number of optional parameters, a subset of those documented in the Writing Data section. of the Connext DDS Core Libraries User’s Manual.
The supported parameters are:
Parameters: - action (str) – One of
"write"
(default),"dispose"
or"unregister"
- source_timestamp (integer) – The source timestamp, an integer representing the total number of nanoseconds
- identity (dict) – A dictionary containing the keys
"writer_guid"
(a list of 16 bytes) and"sequence_number"
(an integer) that uniquely identifies this sample. - related_sample_identity (dict) – Used for request-reply communications. It has the same format as
identity
For example:
output.write( identity={"writer_guid":[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], "sequence_number":1}, timestamp=1000000000)
The write method can block under multiple circumstances (see Blocking During a write() in the Connext DDS Core Libraries User’s Manual). If the blocking time exceeds the max_blocking_time, this method raises
TimeoutError
.- action (str) – One of
5.5.2. Instance class¶
-
class
rticonnextdds_connector.
Instance
(output)¶ A data sample
Instance
is the type ofOutput.instance
and is the object that is published.An Instance has an associated DDS Type, specified in the XML configuration, and it allows setting the values for the fields of the DDS Type.
- Attributes:
output
(Output
): TheOutput
that owns thisInstance
.
- Special methods:
__setitem__
, see Accessing the data.
-
clear_member
(field_name)¶ Resets a member to its default value
The effect is the same as that of
Output.clear_members()
except that only one member is cleared.Parameters: field_name (str) – The name of the field. It can be a complex member or a primitive member. See Accessing the data.
-
get_dictionary
()¶ Retrieves the values of this instance as a dictionary
-
native
¶ Obtains the native C object
This allows accessing additional Connext DDS APIs in C.
-
set_boolean
(field_name, value)¶ Sets a Boolean field
Parameters: - field_name (str) – The name of the field. See Accessing the data.
- value (number) –
True
orFalse
, orNone
to unset an optional member
-
set_dictionary
(dictionary)¶ Sets the member values specified in a dictionary
The dictionary keys are the member names of the Output’s type, and the dictionary values are the values for those members.
This method sets the values of those member that are explicitly specified in the dictionary. Any member that is not specified in the dictionary retains its previous value.
To clear members that are not in the dictionary, you can call
Output.clear_members()
before this method. You can also explicitly set any value in the dictionary toNone
to set that member to its default value.Parameters: dictionary (dict) – The dictionary containing the keys (member names) and values (values for the members)
-
set_number
(field_name, value)¶ Sets a numeric field
Note that this operation should not be used to set values larger than
2^53 - 1
. See Accessing 64-bit integers for more information.Parameters: - field_name (str) – The name of the field. See Accessing the data.
- value (number) – A numeric value or
None
to unset an optional member
-
set_string
(field_name, value)¶ Sets a string field
Parameters: - field_name (str) – The name of the field. See Accessing the data.
- value (str) – The string value or
None
to unset an optional member