Module: dds.pub

class dds.pub.DataWriter

Bases: object

The DDS_DataWriter entity provides an interface for the application to publish (write) data. A DataWriter has a set of Qos Policies (dds.pub.DataWriterQos) that control its behavior. A DataWriter is associated with, and writes on, a single Topic.

assert_liveliness()

This operation manually asserts the liveliness of the DataWriter  dw. This operation is useful if the LIVELINESS QoS setting is MANUAL_BY_PARTICIPANT or MANUAL_BY_TOPIC; otherwise, it has no effect. The  write operation automatically asserts livelines on the DataWriter and its DomainParticipant. Therefore,  assert_liveliness is required only if hte application is not writing data frequently enough to satisfy the LIVELINESS setting.

delete()

This will delete the DataWriter and clean up any contained resources. After this call, the DataWriter must not be used for any other DDS operation.

dispose()

Indicates that the instance no longer exists.

If  handle is not HANDLE_NIL, then  handle must identify a valid instance that has been previously registered or written by this DataWriter. The optional parameter ‘source_timestamp’ can be provided, if it is ‘None’, then the current time is used as the timstamp.

Parameters:
  • data – the object containing (at least) the key value[s]
  • handle – the dds.core.InstanceHandle identifying the instance (can be InstanceHandle.NIL)
  • source_timestampdds.core.Time: the time stamp to use for the operation (if None, use current time)
enable()

Enables the DataWriter.

get_cache_stats()

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

get_guid()

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

get_instance_handle()

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

get_key_value()

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

Parameters:
  • key_holder – this object will be populated with the key values
  • handle (dds.core.InstanceHandle) – the handle of the instance from which to get the key values
get_listener()

This operation returns the currently installed DataWriterListener.

get_liveliness_lost_status()

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

Returns:dds.core.LivelinessLostStatus
get_matched_subscription_data()

This operation returns data that describes a particular matched DataReader identified by ‘handle’. An appropriate handle can be obtained through a call to DataWriter.get_matched_subscriptions().

If ‘handle’ does not identify a matched DataReader, this routine will raise dds.core.PreconditionNotMet.

get_matched_subscriptions()

This operation retrieves the list of DataReaders currently matched with the DataWriter  dw. This list will include the handles that identify DataReaders which have matching Topic and compatible QoS with DataWriter.

If a DataReader has been ignored by a call to DDS_DomainParticipant_ignore_subscription(), then it will not appear in the list.

Returns:list of dds.core.InstanceHandle
get_offered_deadline_missed_status()

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

Returns:dds.core.LivelinessLostStatus
get_offered_incompatible_qos_status()

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

Returns:dds.core.OfferedIncompatibleQosStatus
get_publication_matched_status()

Provides access to the current DDS_PublicationMatchedStatus of the DataWriter. As a side-effect, this routine will reset the  total_count_change and  current_count_change status fields to zero.

Returns:dds.core.PublicationMatchedStatus
get_publisher()

This operation returns the Publisher this DataWriter belongs to.

get_qos()

Returns: dds.pub.DataWriterQos: the current DataWriterQos settings

get_status_changes()

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

If the DataWriter 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 DataWriter. The returned condition can be added to a WaitSet.

Returns: dds.cond.StatusCondition

get_topic()

This operation returns the Topic associated with this DataWriter

is_enabled()

Returns True if the DataWriter is currently enabled; 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.

Parameters:key_data – a data object that contains the key value[s]

Returns: dds.core.InstanceHandle

register_instance()

Declares the existance of an instance identified by the ‘key fields’ in  instance_data. The handle that uniquely identifies the instance is returned. The optional parameter ‘source_timestamp’ can be provided, if it is ‘None’, then the current time is used as the timestamp.

set_listener()

Installs a DataWriterListener on the DataWriter.

Only one listener may be attached to a DataWriter 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 DataWriterQos values. These QoS values affect the behavior of the DataWriter.

Parameters:qos (dds.pub.DataWriterQos) – QoS policy values to set in the datawriter
unregister_instance()

Indicates that the writer will no longer be providing updates the specified instance. If handle is not HANDLE_NIL, then handle must identify a valid instance that has been previously registered or written by this DataWriter. The optional parameter ‘source_timestamp’ can be provided, if it is ‘None’, then the current time is used as the timstamp.

Parameters:
  • data – the data object containing (at least) the key value[s]
  • handle – the dds.core.InstanceHandle identifying the instance (can be InstanceHandle.NIL)
  • source_timestampdds.core.Time: the time stamp to use for the operation (if None, use current time)
wait_for_acknowledgements()

Block until this writer has received acknowledgements for all written data. This routine will block until all data written by the writer has been acknowledged, or until the ‘max_wait’ duration has passed. ‘max_wait’ can be set to INFINITE, in which case this routine may block indefinitely.

dds.core.PreconditionNotMet will be raised if the DataWriter does not require acks

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 publisher can wait
write()

Publishes the provided  instance_data. If  handle is HANDLE_NIL, then the handle is determined from the ‘key fields’ of  instance_data. The optional parameter ‘source_timestamp’ can be provided, if it is ‘None’, then the current time is used as the source timestamp for the published data. This routine may block if RELIABILITY kind == RELIABLE, RESOURCE_LIMITS are not UNLIMITED, and the local resources are exhausted. The routine will block at most ‘max_blocking_time’ as configured in the RELIABLITY QoS. If the routine is still unable to handle the data, after blocking, then DDS_RETCODE_TIMEOUT is returned. The routine may return DDS_RETCODE_OUT_OF_RESOURCES if it is determined that no amount of blocking will allow the data to be processed.

Parameters:
  • data – the object containing data
  • handle – the dds.core.InstanceHandle identifying the instance (can be InstanceHandle.NIL)
  • source_timestampdds.core.Time: the time stamp to use for the operation (if None, use current time)
class dds.pub.DataWriterListener

Bases: object

DataWriterListener holds a set of callbacks that can be invoked by DataWriter

on_liveliness_lost()

Invoked when the ‘liveliness_lost’ status is triggered on the DataWriter

Parameters:
on_offered_deadline_missed()

Invoked when the ‘offered_deadline_missed’ status is triggered on the DataWriter

Parameters:
on_offered_incompatible_qos()

Invoked when the ‘offered_incompatible_qos’ status is triggered on the DataWriter

Parameters:
on_publication_matched()

Invoked when the ‘publication_matched’ status is triggered on the DataWriter

Parameters:
class dds.pub.DataWriterQos

DataWriterQos holds QoS policies relevant for a dds.pub.DataWriter. It contains the following attributes:

durability

dds.qos.DurabilityQosPolicy – The durability policy offered by the DataWriter.

durability_service

dds.qos.DurabilityServiceQosPolicy – The durability service configuration offered by the DataWriter.

deadline

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

latency_budget

dds.qos.LatencyBudgetQosPolicy – The latency offered by the DataWriter.

liveliness

dds.qos.LivelinessQosPolicy – The liveliness mechanism offered by the DataWriter.

reliability

dds.qos.ReliabilityQosPolicy – The transport reliability offered by the DataWriter.

destination_order

dds.qos.DestinationOrderQosPolicy – The destination order logic offered by the DataWriter.

history

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

resource_limits

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

transport_priority

dds.qos.TransportPriorityQosPolicy – The transport priority supported by the DataWriter.

lifespan

dds.qos.LifespanQosPolicy – The expiration time for old samples managed by the DataWriter.

user_data

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

ownership

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

ownership_strength

dds.qos.OwnershipStrengthQosPolicy – The type of ‘ownership strength’ offered by the DataWriter.

writer_data_lifecycle

dds.qos.WriterDataLifecycleQosPolicy – Indicates if unregistered instances should be automatically disposed by the DataWriter.

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.

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_writer

dds.qos.RTPSWriterQosPolicy – rtps_writer configuration

class dds.pub.Publisher

Bases: object

The Publisher configures, creates, manages and destroys DataWriter entities.

begin_coherent_changes()

This operation is not yet implemented.

copy_from_topic_qos()

This operation copies the QoS settings in  a_topic_qos to the corresponding settings in a datawriter_qos. The datawriter_qos parameter is populated with a copy of the QoS policies from the topic_qos structure. QoS entries in the datawriter qos structure will be overwritten with the values from the topic.

Returns: DataWriterQos on success

Raises: dds.core.Error on failure

delete()

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

delete_contained_entities()

This operation deletes all the DataWriters created by this Publisher

This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained DataWriter objects. If any of the objects cannot be deleted, this routine will raise dds.core.PreconditionNotMet.

enable()

Enables the DDS_Publisher. A Publisher is created either enabled or not based on the DomainParticipantQos.entity_factory setting. When a Publisher is not enabled, only the following sub-set of all Publisher operations are legal:

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

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

end_coherent_changes()

This operation is not yet implemented.

get_default_datawriter_qos()

Provides access to the default DataWriterQos settings held in the Publisher  p. The provided  qos argument is populated with the current default qos settings.

Returns: dds.pub.DataWriterQos on success

Raises: dds.core.Error on failure

get_instance_handle()

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

get_listener()

This operation returns the currently installed PublisherListener.

get_participant()

This operation returns the dds.domain.DomainParticipant this Publisher belongs to.

get_qos()

Returns: dds.pub.PublisherQos: the current PublisherQos settings

get_status_changes()

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

If the Publisher 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 Publisher itself and does not include statuses from contained  DataWriter objects.

get_statuscondition()

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

is_enabled()

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

lookup_datawriter()

This operation retrieves a previously-created DataWriter contained in the Publisher, attached to a Topic named topic_name. If multiple DataWriters are found, one of them will be returned. If no matching DataWriter is found, this routine will return None.

Parameters:topic_name (string) – the topic name of interest
resume_publications()

This operation is not yet implemented.

set_default_datawriter_qos()

Sets the default DDS_DataWriterQos held in the Publisher.

This default qos will be used during subsequent calls to create a DataWriter. if the special DDS_DATAWRITER_QOS_DEFAULT value is provided for  qos.

This routine may fail if the provided  qos argument is not internally consistent. In this case, DDS_INCONSISTENT_POLICY will be returned, and no changes will be made to the Publisher.

Parameters:qos (dds.pub.DataWriterQos) – QoS policy values to store
set_listener()

Installs a PublisherListener on Publisher  p.

Only one listener may be attached to a Publisher 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 PublisherQos values. These QoS values affect the behavior of the Publisher.

Parameters:qos (dds.pub.PublisherQos) – QoS policy values to set in the publisher
suspend_publications()

This operation is not yet implemented.

wait_for_acknowledgements()

Block until all writers contained by this publisher have received acknowledgements.

This routine will block until all data written by contained writers has been acknowledged, or until the ‘max_wait’ duration has passed. ‘max_wait’ can be set to Duration.infinite(), in which case this routine may block indefinitely.

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 publisher can wait
class dds.pub.PublisherListener

Bases: object

PublisherListener holds a set of callbacks that can be invoked by Publisher.

on_liveliness_lost()

Invoked when the ‘liveliness_lost’ status is triggered on any contained DataWriter

Parameters:
on_offered_deadline_missed()

Invoked when the ‘offered_deadline_missed’ status is triggered on any contained DataWriter

Parameters:
on_offered_incompatible_qos()

Invoked when the ‘offered_incompatible_qos’ status is triggered on any contained DataWriter

Parameters:
on_publication_matched()

Invoked when the ‘publication_matched’ status is triggered on any contained DataWriter

Parameters:
class dds.pub.PublisherQos

PublisherQos holds QoS policies relevant for a dds.pub.Publisher. 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