Module: dds.sub

class dds.sub.DataReader

Bases: object

DataReader provides access to the data (or subset thereof) available on a Topic.

create_querycondition()

Creates a QueryCondition. The returned QueryCondition can be used as an argument to DataReader.read_w_condition() or DataReader.take_w_condition().

The query_expression is an SQL like condition expression, and query_parameters provide optional parameters that are referenced by the query_expression. The syntax of the query expression is similar to the WHERE clause in SQL. For example “x<4” is a valid query expression. It would test that data member ‘x’ is less than value ‘4’. If the query expression evaluates to TRUE, then the data sample will be available, otherwise the data sample will be ‘filtered’ (excluded).

CoreDX DDS supports the ‘<b>LIKE</b>’ operator (and NOT LIKE) for regular expression string matching. The pattern string in a LIKE clause can contain ‘%’ to match zero or more characters, ‘_’ to match a single character, or ‘[&lt;characters&gt;]’ to match a range of characters.

CoreDX DDS also includes support for the ‘<b>IN</b>’ operator. This provides a very powerful mechanism for testing that a value appears in a set of values. For example “symbol IN (‘ge’, ‘msft’, ‘ibm’)” will select all samples that have a symbol value of ‘ge’, ‘msft’, or ‘ibm’. This could also be written as a series of equality tests combined with the OR operator; however, the IN operator is much more efficient. A query that matches on several hundred or even thousands of values can be implemented very efficiently using the ‘IN’ operator.

The query_expression can refer to parameters. The syntax for paramters is the percent sign ‘%’ followed by a number. The number is the index of the paramter in the  query_paramters sequence. Parameters are counted starting at zero. So, “%0” refers to the first parameter, and “%4” refers to the fifth paramter. Using this syntax, the expression “x<%0” would test the value of ‘x’ against the first parameter in the sequence.

Parameters:
  • sample_states( – class:dds.core.SampleState): the sample states of interest
  • view_states( – class:dds.core.ViewState): the view states of interest
  • instance_states( – class:dds.core.InstanceState): the instance states of interest
  • query_expression (string) – The sql like filter expression
  • query_parameters (list of strings) – The list of parameters to the query expression; can be empty

Returns: (dds.cond.QueryCondition) or None

Currently unsupported - will raise dds.core.Unsupported

create_readcondition()

Creates a ReadCondition associated with this DataReader. The returned condition can be added to a WaitSet or used in a call to the specialized  read() or  take() operations. For example see DataReader.read_w_condition().

Parameters:
  • sample_states( – class:dds.core.SampleState): the sample states of interest
  • view_states( – class:dds.core.ViewState): the view states of interest
  • instance_states( – class:dds.core.InstanceState): the instance states of interest
delete()

This will invoke delete_contained_entities() on the DataReader, and then delete the DataReader itself. After this call, the DataReader must not be used for any other DDS operation.

delete_contained_entities()

This operation deletes all the ReadCondition and QueryCondition objects previously created by means of the DataReader.create_readcondition() and DataReader.create_querycondition() operations.

<p>If any of the objects cannot be deleted, this routine will return RETCODE_PRECONDITION_NOT_MET.

delete_readcondition()

Destroys a ReadCondition (or QueryCondition). The provided condition must have been previously created via a call to DataReader.create_readcondition() or DataReader.create_querycondition().

The condition argument must belong to the DataReader. Otherwise, the error dds.core.PreconditionNotMet will be raised.

If the DataReader is actively processing the ReadCondition, this routine will raise dds.core.Error; in this case, the delete_readcondition() call can be re-tried.

Parameters:condition (dds.cond.ReadCondition) – the read condition to delete
enable()

Enables the DataReader. Raises dds.core.Error etal on failure.

get_cache_stats()

Provides access to the current cache statistics of the DataReader. This routine will populate ‘stats’ with the current statistics.

Currently unsupported - will raise dds.core.Unsupported

get_guid()

Returns the 16 byte GUID (dds.core.GUID) that identifies this Reader within its domain.

get_instance_handle()

This operation returns the InstanceHandle_t that identifies the DataReader.

get_key_value()

This routine will populate the data structure indicated by ‘data’ with the key infomation identified by ‘handle’. This routine is data type specific.

Parameters:
get_listener()

This operation returns the currently installed DataReaderListener.

get_liveliness_changed_status()

Provides access to the current DDS_LivelinessChangedStatus of the DataReader. As a side-effect, this routine will reset the  total_count_change status field to zero.

Returns: dds.core.LivelinessChangedStatus

get_matched_publication_data()

This operation returns data that describes a particular matched DataWriter identified by the provided publication_handle. An appropriate handle can be obtained through a call to DataReader.get_matched_publications().

If publication_handle does not identify a matched DataWriter, this routine will raise dds.core.PreconditionNotMet.

Parameters:pub_handle (dds.core.InstanceHandle) –
get_matched_publication_guid()

<extension> Get the 16 byte GUID (dds.core.GUID) that identifies the DataWriter (from the publication handle).

get_matched_publications()

This operation retrieves the list of DataWriters currently matched with the DataReader dr. This list will include the handles that identify DataWriters which have matching Topic and compatible QoS with DataReader.

get_qos()

Returns: dds.sub.DataReaderQos: the current DataReaderQos settings

get_requested_deadline_missed_status()

Provides access to the current DDS_RequestedDeadlineMissedStatus of the DataReader. As a side-effect, this routine will reset the  total_count_change status field to zero.

Returns: dds.core.RequestedDeadlineMissedStatus

get_requested_incompatible_qos_status()

Provides access to the current DDS_RequestedIncompatibleQosStatus of the DataReader. As a side-effect, this routine will reset the  total_count_change status field to zero.

Returns: dds.core.RequestedIncompatibleQosStatus

get_sample_lost_status()

Provides access to the current DDS_SampleLostStatus of the DataReader. As a side-effect, this routine will reset the  total_count_change status field to zero.

Returns: dds.core.SampleLostStatus

get_sample_rejected_status()

Provides access to the current DDS_SampleRejectedStatus of the DataReader. As a side-effect, this routine will reset the  total_count_change status field to zero.

Returns: dds.core.SampleRejectedStatus

get_status_changes()

This returns the list of  triggered communication statuses in the DataReader.

If the DataReader is not enabled, all statuses will be  untriggered. The list returned by get_status_changes may be empty. The list of statuses returned by

get_statuscondition()

This operation allows access to the StatusCondition associated with the DataReader. The returned condition can be added to a WaitSet.

get_subscriber()

This operation returns the Subscriber this DataReader belongs to.

get_subscription_matched_status()

Provides access to the current DDS_SubscriptionMatchedStatus of the DataReader. As a side-effect, this routine will reset the  total_count_change status field to zero.

Returns: dds.core.SubscriptionMatchedStatus

get_topicdescription()

This operation returns the TopicDescription associated with this DataReader

is_enabled()

Checks if the DataReader is enabled, returns True if it is, False otherwise.

lookup_instance()

Returns the handle that identifies the data instance provided in instance_data. The ‘key’ field values of the data are associated with a unique handle. This routine is data type specific.

Parameters:key_data (object) –
read()

This operation accesses a collection of data values (with associated SampleInfo) within the DataReader.

Returns [ data_seq, info_seq ].

This routine, and the related take(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.

The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).

The specific behavior of read() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data.

The argument max_samples is used to limit the total number of samples returned.

The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired ‘states’ for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special ‘ANY’ constants (e.g.: ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.

The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.

The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated ‘meta-data’. See SampleInfo for a description of this meta-data.

In CoreDX DDS, the returned sequences contain ‘loaned’ data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is ‘loaned’ to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling DataReader_return_loan().

The read() operation will set the SampleInfo::sample_state to READ_SAMPLE_STATE.

The read() operation may set the SampleInfo::view_state to NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is read.

If there is no data found, then the read() will return RETCODE_NO_DATA.

@note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

read_instance()

This operation accesses a collection of data values (with associated ampleInfo), belonging to a particular instance, within the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

read_next_instance()

This operation accesses a collection of data values (with associated SampleInfo), instance by instance, within the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

read_next_instance_w_condition()

This operation accesses a collection of data values (with associated DDS_SampleInfo), instance by instance subject to a filter, within the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

read_next_sample()

This operation accesses a data value (with associated SampleInfo) within the DataReader.

read_w_condition()

This operation accesses a collection of data values (with associated SampleInfo), subject to a filter, within the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

return_loan()

Returns data and sample_info values to a DataReader.

When an application calls DataReader read() or take() operations, these routines ‘loan’ data and SampleInfo values to the application. [This is an optimization that avoids extra copies of data.] The appliction must return this ‘loaned’ data to the DataReader. The return_loan() routine indicates to the DataReader that the application no longer requires access to the data and sample_infos.

A call to return_loan() operation must be called only if previous read() or take() calls ‘loaned’ data to the application.

If the received_data or sample_infos parameters provided do not identify data obtained from DataReader dr, then the error PreconditionNotMet will be raised.

Note: A DataReader cannot be deleted if any ‘loans’ are outstanding.

set_listener()

Installs a DataReaderListener on the DataReader.

Only one listener may be attached to a DataReader at a time. A call to set_listener() will replace any current listener with the provided listener. <p>Parameter listener can be None, which indicates a listener that does nothing.

Parameters:
set_qos()

Sets the DataReaderQos values. These QoS values affect the behavior of the DataReader.

Parameters:qos (dds.sub.DataReaderQos) – QoS policy values to set in the DataReader
take()

This operation takes a collection of data values (with associated SampleInfo) from the DataReader. This routine, and the related  read(), provide the interface for an application to access published data. There are several varieties of  read() and  take(), to facilitate different access patterns or approaches. <p>The primary difference between  read() and  take() is that  take() removes all returned data samples from the DataReader while  read() does not. Sequential  read() calls will return the same data samples each time (if nothing else changes); while sequential  take() calls will return data samples for only the first call. Subsequent  take() calls will return an empty collection (if no new data arrives). <p>The specific behavior of  take() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the  received_data and  sample_infos arguments affect the following: - how many samples are returned, and - whether the returned data should be ‘loaned’ or copied. <p>The argument  max_samples is used to further limit the number of samples returned. <p>The  sample_states,  view_states, and  instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired ‘states’ for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special ‘ANY’ constants (e.g.: ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection. <p>The order of samples in the returned collections is determined by the  PRESENTATION and  DESTINATION_ORDER QoS policies. <p>The returned collection is held in  recieved_data and  samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in  received_data has a corresponding entry in  sample_infos that provides associated ‘meta-data’. See SampleInfo for a description of this meta-data. <p>In CoreDX DDS, the returned sequences contain ‘loaned’ data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is ‘loaned’ to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling DataReader_return_loan(). <p>The  take() operation will set the SampleInfo::sample_state to READ_SAMPLE_STATE. <p>The  take() operation may set the SampleInfo::view_state to NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is taken. <p>If there is no data found, then the  take() will return RETCODE_NO_DATA. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

take_instance()

This operation takes a collection of data values (with associated SampleInfo), belonging to a particular instance, from the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

take_next_instance()

This operation takes a collection of data values (with associated DDS_SampleInfo), instance by instance, from the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

take_next_instance_w_condition()

This operation takes a collection of data values (with associated DDS_SampleInfo), instance by instance subject to a filter, from the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

take_next_sample()

This operation takes a data value (with associated SampleInfo) from the DataReader. @note This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

take_w_condition()

This operation takes a collection of data values (with associated SampleInfo), subject to a filter, from the DataReader. This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

wait_for_historical_data()

This routine blocks until all ‘historical’ data is received.

dds.core.Timeout will be raised if ‘max_wait’ passes before all acks are received.

Parameters:max_wait (dds.core.Duration) – the amount of time the DataReader can wait
class dds.sub.DataReaderListener

Bases: object

DataReaderListener holds a set of callbacks that can be invoked by DataReader

on_data_available()

Invoked when the ‘data_available’ status is triggered on the DataReader

Parameters:reader (dds.sub.DataReader) – the DataReader of concern
on_liveliness_changed()

Invoked when the ‘liveliness_changed’ status is triggered on the DataReader

Parameters:
on_requested_deadline_missed()

Invoked when the ‘requested_deadline_missed’ status is triggered on the DataReader

Parameters:
on_requested_incompatible_qos()

Invoked when the ‘requested_incompatible_qos’ status is triggered on the DataReader

Parameters:
on_sample_lost()

Invoked when the ‘sample_lost’ status is triggered on the DataReader

Parameters:
on_sample_rejected()

Invoked when the ‘sample_rejected’ status is triggered on the DataReader

Parameters:
on_subscription_matched()

Invoked when the ‘subscription_matched’ status is triggered on the DataReader

Parameters:
class dds.sub.DataReaderQos

DataReaderQos holds QoS policies relevant for a dds.sub.DataReader. It contains the following attributes:

durability

dds.qos.DurabilityQosPolicy – The durability policy requested by the DataReader.

deadline

dds.qos.DeadlineQosPolicy – The requested update frequency for data instances.

latency_budget

dds.qos.LatencyBudgetQosPolicy – The latency requested by the DataReader.

liveliness

dds.qos.LivelinessQosPolicy – The liveliness mechanism requested by the DataReader.

reliability

dds.qos.ReliabilityQosPolicy – The transport reliability requested by the DataReader.

destination_order

dds.qos.DestinationOrderQosPolicy – The destination order logic requested by the DataReader.

history

dds.qos.HistoryQosPolicy – The data history supported by the DataReader.

resource_limits

dds.qos.ResourceLimitsQosPolicy – The resource limits set on the DataReader.

user_data

dds.qos.UserDataQosPolicy – A sequence of octets associated with the DataReader.

ownership

dds.qos.OwnershipQosPolicy – The type of ‘ownership’ offered by the DataReader.

time_based_filter

dds.qos.TimeBasedFilterQosPolicy – The maximum update frequency required/desired by the DataReader.

reader_data_lifecycle

dds.qos.ReaderDataLifecycleQosPolicy – Controls the auto-purge behavior of the DataReader.

representation

dds.qos.DataRepresentationQosPolicy – Informs DataReaders(s) of the data representation(s) provided by this Writer. This must be consistent with the TypeSupport associated with the Writer’s Topic.

type_consistency

dds.qos.TypeConsistencyQosPolicy – Influences the algorithm that matches DataReaders and DataWriters based on their data type compatibility.

rpc

dds.qos.RpcQosPolicy – Configure RPC relevant settings: instance_name, related_entity, and topic_aliases.

data_tags

dds.qos.DataTagQosPolicy – Security related data_tags (sequence of name,value pairs).

entity_name

dds.qos.EntityNameQosPolicy – entity name

logging

dds.qos.LoggingQosPolicy – logging

rtps_reader

dds.qos.RTPSReaderQosPolicy – rtps_reader configuration

class dds.sub.Subscriber

Bases: object

The Subscriber configures, creates, and manages DataReaders.

begin_access()

This operation indicates that the application is about to access the data samples in any of the DataReader objects contained in the Subscriber  s. The application is expected to use this operation only if PRESENTATION QosPolicy of the Subscriber has the access_scope set to GROUP. [Otherwise this routine has no effect.]

copy_from_topic_qos()

This operation merges the QoS settings from ‘topic_qos’ with the settings in dr_qos to construct a new DataReaderQos object. The resulting DataReaderQos object is returned. The ‘dr_qos’ object is not modified.

Parameters:
delete()

This will invoke delete_contained_entities() on the Susbscriber, and then delete the Subscriber itself. After this call, the Subscriber must not be used for any other DDS operation.

delete_contained_entities()

This operation deletes all the DataReaders created within this Subscriber. This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained DataReader objects. If successful, this operation will recursively delete all objects contained with this Subscriber. If any of the objects cannot be deleted, this routine will raise :class:dds.core.PreconditionNotMet.

enable()

Enables the Subscriber. A Subscriber is created either enabled or not based on the dds.domain.DomainParticipantQos.entity_factory setting.

When a Subscriber is not enabled, only the following sub-set of all Subscriber operations are legal:

  • operations to get and set QoS policies,
  • factory operations (create, delete),
  • get_statuscondition(),
  • get_status_changes(),
  • lookup operations

Any other Subscriber operation may raise a dds.core.NotEnabled error. Subscriber.enable() may be called on an already enabled Subscriber [it will have no effect].

end_access()

This operation closes a corresponding Subscriber.begin_access().

get_datareaders()

This operation allows the application to access DataReader objects that contain samples with the specified  sample_states,  view_states, and  instance_states.

If the PRESENTATION QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to GROUP, this operation should be invoked only inside a begin_access/end_access block. Otherwise it will return the error PRECONDITION_NOT_MET. <p>The returned collection of DataReader objects may either be a set (containing each DataReader at most once in no specified order), or a list (containing each DataReader one or more times in a specific order).

  • If PRESENTATION access_scope is INSTANCE or TOPIC, the returned collection is a set.
  • If PRESENTATION access_scope is GROUP and ordered_access is set to TRUE, then the returned collection is a list.

This difference supports alternate access mechanisms.

Parameters:
  • sample_states( – class:dds.core.SampleState)
  • view_states( – class:dds.core.ViewState)
  • instance_states( – class:dds.core.InstanceState)
get_default_datareader_qos()

Provides access to the default DataReaderQos settings held in the Subscriber. A populated DataReaderQos object is returned.

get_instance_handle()

This operation returns the dds.core.InstanceHandle that identifies the Subscriber.

get_listener()

This operation returns the currently installed SubscriberListener.

get_participant()

This operation returns the DomainParticipant this Subscriber belongs to.

get_qos()

Returns: dds.sub.SubscriberQos: the current SubscriberQos settings The return value is populated with a copy of the current Subscriber QoS properties.

get_status_changes()

This returns the list of triggered communication statuses in the Subscriber.

If the Subscriber is not enabled, all statuses will be untriggered. The list returned by get_status_changes may be empty. The list of statuses returned by get_status_changes operation contains statuses that are triggered on the Subscriber itself and does not include statuses from contained DataWriter objects.

get_statuscondition()

This operation allows access to the StatusCondition associated with the Subscriber. The returned condition can be added to a WaitSet.

is_enabled()

Returns True if the publisher is currently enabled; False otherwise.

lookup_datareader()

This operation retrieves a previously-created DataReader contained in the Subscriber, attached to a Topic named topic_name. If multiple DataReaders are found, one of them will be returned. If no matching DataReader is found, this routine will return None. This routine is useful to obtain access to a particular built-in DataReader.

Parameters:topic_name (string) – the topic of interest
notify_datareaders()

This operation invokes the DataReaderListener on_data_available operation on any contained DataReader entities with a DATA_AVAILABLE status that is considered changed.

set_default_datareader_qos()

Sets the default DataReaderQos held in the Subscriber. This default qos will be used during subsequent calls to create a DataReader with this Subscriber, if the value None is provided for qos.

This routine may fail if the provided qos argument is not internally consistent. In this case, dds.core.InconsistentPolicy will be raised, and no changes will be made to the Subscriber.

The subscriber makes a copy of the provided qos.

Parameters:qos (dds.sub.DataReaderQos) – the DataReader QoS to store as default
set_listener()

Installs a SubscriberListener on the Subscriber.

Only one listener may be attached to a Subscriber at a time. A call to set_listener() will replace any current listener with the provided listener.

Parameter ‘listener’ can be None, which indicates a listener that does nothing.

Parameters:
set_qos()

Sets the SubscriberQos values. These QoS values affect the behavior of the Subscriber.

Parameters:qos (dds.sub.SubscriberQos) – QoS policy values to set in the Subscriber
class dds.sub.SubscriberListener

Bases: object

SubscriberListener holds a set of callbacks that can be invoked by Subscriber

on_data_available()

Invoked when the ‘data_available’ status is triggered on any contained DataReader

Parameters:reader (dds.sub.DataReader) – the DataReader of concern
on_data_on_readers()

Invoked when the ‘data_on_readers’ status is triggered on the Subscriber

Parameters:subscriber (dds.sub.Subscriber) – the subscriber of concern
on_liveliness_changed()

Invoked when the ‘liveliness_changed’ status is triggered on any contained DataReader

Parameters:
on_requested_deadline_missed()

Invoked when the ‘requested_deadline_missed’ status is triggered on any contained DataReader

Parameters:
on_requested_incompatible_qos()

Invoked when the ‘requested_incompatible_qos’ status is triggered on any contained DataReader

Parameters:
on_sample_lost()

Invoked when the ‘sample_lost’ status is triggered on any contained DataReader

Parameters:
on_sample_rejected()

Invoked when the ‘sample_rejected’ status is triggered on any contained DataReader

Parameters:
on_subscription_matched()

Invoked when the ‘subscription_matched’ status is triggered on any contained DataReader

Parameters:
class dds.sub.SubscriberQos

SubscriberQos holds QoS policies relevant for a dds.sub.Subscriber. It contains the following attributes:

presentation

dds.qos.PresentationQosPolicy

partition

dds.qos.PartitionQosPolicy

group_data

dds.qos.GroupDataQosPolicy

entity_factory

dds.qos.EntityFactoryQosPolicy

entity_name

dds.qos.EntityNameQosPolicy

logging

dds.qos.LoggingQosPolicy