6. Reading Data (Input)¶

6.1. Getting the input¶

To read/take samples, first get a reference to the Input:

input = connector.get_input("MySubscriber::MySquareReader")

Connector.get_input() returns a Input object. This example obtains the input defined by the <data_reader> named MySquareReader within the <subscriber> named MySubscriber:

<subscriber name="MySubscriber">
  <data_reader name="MySquareReader" topic_ref="Square" />
</subscriber>

This <subscriber> is defined inside the <domain_participant> selected to create this connector (see Creating a new Connector).

6.2. Reading or taking the data¶

Call Input.take() to access and remove the samples:

input.take()

or Input.read() to access the samples but leave them available for a future read() or take():

input.read()

The method Input.wait() can be used to identify when there is new data available on a specific Input. It will block until either the supplied timeout expires (in which case it will raise a TimeoutError) or until new data is available:

input.wait()

The method Connector.wait() has the same behavior as Input.wait(), but will block until data is available on any of the Input objects within the Connector:

connector.wait()

6.3. Accessing the data samples¶

After calling Input.read() or Input.take(), Input.samples contains the data samples:

for sample in input.samples:
   if sample.valid_data:
      print(sample.get_dictionary())

SampleIterator.get_dictionary() retrieves all the fields of a sample.

Unless the Samples.valid_data_iter is used, it is necessary to check if the sample contains valid data before accessing the fields. The only exception to this rule is if the instance_state of the sample is "NOT_ALIVE_DISPOSED". See Accessing key values of disposed samples for more information on this use case.

If you don’t need to access the meta-data (see Accessing sample meta-data), the simplest way to access the data is to use Samples.valid_data_iter to skip samples with invalid data:

for sample in input.samples.valid_data_iter:
   print(sample.get_dictionary())

It is also possible to access an individual sample:

if input.samples.length > 0:
   if input.samples[0].valid_data:
      print(input.samples[0].get_dictionary())

Warning

All the methods described in this section return iterators to samples. Calling read/take again invalidates all iterators currently in use. For that reason, it is not recommended to store any iterator.

get_dictionary() can receive a field_name to only return the fields of a complex member. In addition to get_dictionary(), you can get the values of specific primitive fields using SampleIterator.get_number(), SampleIterator.get_boolean() and SampleIterator.get_string(). For example:

for sample in input.samples.valid_data_iter:
   x = sample.get_number("x") # or just sample["x"]
   y = sample.get_number("y")
   size = sample.get_number("shapesize")
   color = sample.get_string("color") # or just sample["color"]

See more information and examples in Accessing the data.

6.4. Accessing sample meta-data¶

Every sample contains an associated SampleInfo with meta-information about the sample:

for sample in input.samples:
   source_timestamp = sample.info["source_timestamp"]

See SampleIterator.info() for the list of available meta-data fields.

Connext DDS can produce samples with invalid data, which contain meta-data only. For more information about this, see Valid Data Flag in the RTI Connext DDS Core Libraries User’s Manual. These samples indicate a change in the instance state. Samples with invalid data still provide the following information:

The SampleInfo
When an instance is disposed (sample.info.get('instance_state') is 'NOT_ALIVE_DISPOSED'), the sample data contains the value of the key that has been disposed. You can access the key fields only. See Accessing key values of disposed samples.

6.5. Matching with a publication¶

Use the method Input.wait_for_publications() to detect when a compatible DDS publication is matched or stops matching. It returns the change in the number of matched publications since the last time it was called:

change_in_matches = input.wait_for_publications()

For example, if a new compatible publication is discovered within the specified timeout, the function returns 1; if a previously matching publication no longer matches, it returns -1.

You can obtain information about the existing matched publications with Input.matched_publication:

matched_pubs = input.matched_publications
for pub_info in matched_pubs:
   pub_name = pub_info['name']

6.6. Class reference: Input, Samples, SampleIterator¶

6.6.1. Input class¶

class rticonnextdds_connector.Input(connector, name)¶

Allows reading data for a Topic

To get an input object, use Connector.get_input().

Attributes:

connector (Connector): The Connector that created this Input
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.

matched_publications¶

Returns information about the matched publications

This property returns a list where each element is a dictionary with information about a publication matched with this Input.

Currently, the only key in the dictionaries is "name", containing the publication name. If a publication doesn’t have name, the value for the key name is None.

Note that Connector Outputs are automatically assigned a name from the data_writer name in the XML configuration.

read()¶

Access the samples received by this Input

This operation performs the same operation as take() except that the samples remain accessible.

samples¶

Allows iterating over the samples read by this input

This container provides iterators to access the data samples retrieved by the most-recent call to read() or take().

Return type:	`Samples`

take()¶

Accesses the sample received by this Input

After calling this method, the samples are accessible from samples

wait(timeout=None)¶

Wait for this input to receive data.

This method waits for the specified timeout for data to be received by this input. If the operation times out, it raises TimeoutError.

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

wait_for_publications(timeout=None)¶

Waits until this input matches or unmatches a compatible DDS subscription.

If the operation times out, it will raise TimeoutError.

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).

6.6.2. Samples class¶

class rticonnextdds_connector.Samples(input)¶

Provides access to the data samples read by an Input (Input.samples)

This class provides the special method __iter__ to iterate over the data samples and __getitem__ to access a specific sample by index. Both return the type SampleIterator.

The default iterator provides access to all the data samples retrieved by the most-recent call to read() or take(). Use valid_data_iter() to access only samples with valid data.

Samples is the type of the property Input.samples.

For more information and examples see Accessing the data samples.

Special methods:

__getitem__ gets a sample by index: input.samples[i]
__iter__ enables iteration: for s in input.samples: ...

length¶

Returns the number of samples available

Returns:	The number of samples available since the last time read/take was called

valid_data_iter¶

Returns an iterator to the data samples with valid data

The iterator provides access to the data samples retrieved by the most-recent call to Input.read() or Input.take(), and skips samples with invalid data (meta-data only).

To access all samples, including those with meta-data only, iterate over Input.samples directly.

By using this iterator, it is not necessary to check if each sample contains valid data.

Returns:	An iterator to the data samples with valid
Return type:	`ValidSampleIterator`

6.6.3. SampleIterator class¶

class rticonnextdds_connector.SampleIterator(input, index=-1)¶

Iterates and provides access to a data sample

A SampleIterator provides access to the data received by an input. SampleIterator is the iterator type of Input.samples.

See Reading Data (Input).

Special methods:

__getitem__ retrieves a field, see Accessing the data
__iter__ enables iteration
__next__ moves to the next sample

get_boolean(field_name)¶

Gets the value of a boolean field in this sample

Parameters:	field_name (str) – The name of the field. See Accessing the data.
Returns:	The boolean value for the field `field_name`.

get_dictionary(member_name=None)¶

Gets a dictionary with the values of all the fields of this sample

The dictionary keys are the field names and the dictionary values correspond to each field value. To see how nested types, sequences, and arrays are represented, see Accessing the data.

Parameters:	member_name (str) – (Optional) The name of the complex member or field. The type of the member with name member_name must be an array, sequence, struct, value or union.
Returns:	A dictionary containing all the fields of the sample, or if a member_name is supplied, all the fields or elements of that member.

get_number(field_name)¶

Gets the value of a numeric field in this sample

Note that this operation should not be used to retrieve values larger than 2^53. See Accessing 64-bit integers for more information.

Parameters:	field_name (str) – The name of the field. See Accessing the data.
Returns:	The numeric value for the field `field_name`.

get_string(field_name)¶

Gets the value of a string field in this sample

Parameters:	field_name (str) – The name of the field. See Accessing the data.
Returns:	The string value for the field `field_name`.

info¶

Provides access to this sample’s meta-data

The info object expects one of the SampleInfo field names:

value = sample_it.info[field]

Supported fields:

"source_timestamp", returns an integer representing nanoseconds
"reception_timestamp", returns an integer representing nanoseconds
"sample_identity", or "identity" returns a dictionary (see Output.write())
"related_sample_identity" returns a dictionary (see Output.write())
"valid_data", returns a boolean (equivalent to sample_it.valid_data)
"view_state", returns a string (either “NEW” or “NOT_NEW”)
"instance_state", returns a string (one of “ALIVE”, “NOT_ALIVE_DISPOSED” or “NOT_ALIVE_NO_WRITERS”)
"sample_state", returns a string (either “READ” or “NOT_READ”)

These fields are documented in The SampleInfo Structure section in the Connext DDS Core Libraries User’s Manual.

native¶: Returns the native pointer to this sample

next()¶: Moves to the next sample

valid_data¶

Returns whether this sample contains valid data

If this returns False, this object’s getters cannot be called.

6.6.4. ValidSampleIterator class¶

class rticonnextdds_connector.ValidSampleIterator(input, index=-1)¶

Iterates and provides access to data samples with valid data

This iterator provides the same methods as SampleIterator.

See Samples.valid_data_iter().

next()¶: Moves to the next sample