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_timestamp –
dds.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: - listener (
dds.pub.DataWriterListener
) – the listener to install - mask (
dds.core.StatusMask
) – set of bit values (in ‘int’ form) indicating which callbacks should be invoked
- listener (
-
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_timestamp –
dds.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 acksdds.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_timestamp –
dds.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: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.LivelinessLostStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
on_offered_deadline_missed
()¶ Invoked when the ‘offered_deadline_missed’ status is triggered on the DataWriter
Parameters: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.OfferedDeadlineMissedStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
on_offered_incompatible_qos
()¶ Invoked when the ‘offered_incompatible_qos’ status is triggered on the DataWriter
Parameters: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.OfferedIncompatibleQosStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
on_publication_matched
()¶ Invoked when the ‘publication_matched’ status is triggered on the DataWriter
Parameters: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.PublicationMatchedStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
-
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.
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 successRaises:
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: - listener (
dds.pub.PublisherListener
) – the listener to install - mask (
dds.core.StatusMask
) – set of bit values (in ‘int’ form) indicating which callbacks should be invoked
- listener (
-
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: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.LivelinessLostStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
on_offered_deadline_missed
()¶ Invoked when the ‘offered_deadline_missed’ status is triggered on any contained DataWriter
Parameters: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.OfferedDeadlineMissedStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
on_offered_incompatible_qos
()¶ Invoked when the ‘offered_incompatible_qos’ status is triggered on any contained DataWriter
Parameters: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.OfferedIncompatibleQosStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-
on_publication_matched
()¶ Invoked when the ‘publication_matched’ status is triggered on any contained DataWriter
Parameters: - writer (
dds.pub.DataWriter
) – the DataWriter of concern - status (
dds.core.PublicationMatchedStatus
) – provides a snapshot of the status at the time the listener was invoked
- writer (
-