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:

instance (Instance): The data that is written when write() is called.
connector (Connector): The Connector that created this Output
name (str): The name of this Output (the name used in Connector.getOutput())
native: A native handle that allows accessing additional Connext DDS APIs in C.

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 to None.

For example, if this Output’s type is ShapeType (from the previous example), then clear_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 is None.

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 the timeout 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, use clear_members()

This method can also dispose or unregister an instance by passing the argument action="dispose" or action="unregister". In these two cases, only the instance 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.

5.5.2. Instance class¶

class rticonnextdds_connector.Instance(output)¶

A data sample

Instance is the type of Output.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): The Output that owns this Instance.

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` or `False`, or `None` 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 to None 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

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