6. Reading Data (Input)¶
6.1. Getting the input¶
To read/take samples, first get a reference to the
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
<subscriber> named MySubscriber:
<subscriber name="MySubscriber"> <data_reader name="MySquareReader" topic_ref="Square" /> </subscriber>
<subscriber> is defined inside the
to create this
connector (see Creating a new Connector).
6.2. Reading or taking the data¶
Input.take() to access and remove the samples:
Input.read() to access the samples but leave them available for
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:
Connector.wait() has the same behavior as
but will block until data is available on any of the
Input objects within
6.3. Accessing the data 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.
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
See Accessing key values of disposed samples for more information on this use
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.valid_data: print(input.samples.get_dictionary())
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
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"]
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:
- When an instance is disposed (
'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
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¶
Allows reading data for a Topic
To get an input object, use
Connectorthat created this
name(str): The name of this
Output(the name used in
native: A native handle that allows accessing additional Connext DDS APIs in C.
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
Note that Connector Outputs are automatically assigned a name from the data_writer name in the XML configuration.
Access the samples received by this Input
This operation performs the same operation as
take()except that the samples remain accessible.
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
Accesses the sample received by this Input
After calling this method, the samples are accessible from
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
Parameters: timeout (number) – The maximum time to wait in milliseconds. By default, infinite.
Waits until this input matches or unmatches a compatible DDS subscription.
If the operation times out, it will raise
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¶
Provides access to the data samples read by an Input (
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
The default iterator provides access to all the data samples retrieved by the most-recent call to
valid_data_iter()to access only samples with valid data.
Samplesis the type of the property
For more information and examples see Accessing the data samples.
- Special methods:
__getitem__gets a sample by index:
for s in input.samples: ...
Returns the number of samples available
Returns: The number of samples available since the last time read/take was called
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.take(), and skips samples with invalid data (meta-data only).
To access all samples, including those with meta-data only, iterate over
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:
6.6.3. SampleIterator class¶
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
See Reading Data (Input).
- Special methods:
__getitem__retrieves a field, see Accessing the data
__next__moves to the next sample
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
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.
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
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
Provides access to this sample’s meta-data
The info object expects one of the SampleInfo field names:
value = sample_it.info[field]
"source_timestamp", returns an integer representing nanoseconds
"reception_timestamp", returns an integer representing nanoseconds
"identity"returns a dictionary (see
"related_sample_identity"returns a dictionary (see
"valid_data", returns a boolean (equivalent to
"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.
Returns the native pointer to this sample
Moves to the next sample
Returns whether this sample contains valid data
If this returns
False, this object’s getters cannot be called.
6.6.4. ValidSampleIterator class¶
Iterates and provides access to data samples with valid data
This iterator provides the same methods as
Moves to the next sample