Writing Data

You are here:

Writing Data

The write() operation informs Connext DDS that there is a new value for a data-instance to be published for the corresponding Topic. By default, calling write() will send the data immediately over the network (assuming that there are matched DataReaders). However, you can configure and execute operations on the DataWriter’s Publisher to buffer the data so that it is sent in a batch with data from other DataWriters or even to prevent the data from being sent. Those sending “modes” are configured using the PRESENTATION QosPolicy as well as the Publisher’s suspend/resume_publications() operations. The actual transport-level communications may be done by a separate, lower-priority thread when the Publisher is configured to send the data for its DataWriters. For more information on threads, see Connext DDS Threading Model.

When you call write(), Connext DDS automatically attaches a stamp of the current time that is sent with the DDS data sample to the DataReader(s). The timestamp appears in the source_timestamp field of the DDS_SampleInfo structure that is provided along with your data using DataReaders (see The SampleInfo Structure).

DDS_ReturnCode_t  write (const Foo &instance_data, 
    const DDS_InstanceHandle_t &handle)

You can use an alternate DataWriter operation called write_w_timestamp(). This performs the same action as write(), but allows the application to explicitly set the source_timestamp. This is useful when you want the user application to set the value of the timestamp instead of the default clock used by Connext DDS.

DDS_ReturnCode_t  write_w_timestamp (
	const Foo &instance_data,
	const DDS_InstanceHandle_t &handle, 
	const DDS_Time_t &source_timestamp)

Note that, in general, the application should not mix these two ways of specifying timestamps. That is, for each DataWriter, the application should either always use the automatic timestamping mechanism (by calling the normal operations) or always specify a timestamp (by calling the “w_timestamp” variants of the operations). Mixing the two methods may result in not receiving sent data.

You can also use an alternate DataWriter operation, write_w_params(), which performs the same action as write(), but allows the application to explicitly set the fields contained in the DDS_WriteParams structure, see DDS_WriteParams_t.

DDS_WriteParams_t
Type	Field Name	Description
DDS_Boolean	replace_auto	Allows retrieving the actual value of those fields that were automatic. When this field is set to true, the fields that were configured with an automatic value (for example, DDS_AUTO_SAMPLE_IDENTITY in identity) receive their actual value after write_w_params is called.
DDS_ SampleIdentity_t	identity	Identity of the DDS sample being written. The identity consists of a pair (Virtual Writer GUID, Virtual Sequence Number). When the value DDS_AUTO_SAMPLE_IDENTITY is used, the write_w_params() operation will determine the DDS sample identity as follows: The Virtual Writer GUID (writer_guid) is the virtual GUID associated with the DataWriter writing the DDS sample. This virtual GUID is configured using the member virtual_guid in DATA_WRITER_PROTOCOL_STATUS. The Virtual Sequence Number (sequence_number) is increased by one with respect to the previous value. The virtual sequence numbers for a given virtual GUID must be strictly monotonically increasing. If you try to write a DDS sample with a sequence number smaller or equal to the last sequence number, the write operation will fail. A DataReader can inspect the identity of a received DDS sample by accessing the fields original_publication_virtual_guid and original_publication_virtual_sequence_number in The SampleInfo Structure.
DDS_ SampleIdentity_t	related_sample_ identity	The identity of another DDS sample related to this one. The value of this field identifies another DDS sample that is logically related to the one that is written. For example, the DataWriter created by a Replier (sets Introduction to the Request-Reply Communication Pattern) uses this field to associate the identity of the DDS request sample to reponse sample. To specify that there is no related DDS sample identity use the value DDS_UNKNOWN_SAMPLE_IDENTITY, A DataReader can inspect the related DDS sample identity of a received DDS sample by accessing the fields related_original_publication_virtual_guid and related_original_publication_virtual_sequence_number in The SampleInfo Structure.
DDS_Time	source_timestamp	Source timestamp that will be associated to the DDS sample that is written. If source_timestamp is set to DDS_TIMER_INVALID, the middleware will assign the value. A DataReader can inspect the source_timestamp value of a received DDS sample by accessing the field source_timestamp The SampleInfo Structure.
DDS_ InstanceHandle_t	handle	The instance handle. This value can be either the handle returned by a previous call to register_instance() or the special value DDS_HANDLE_NIL.
DDS_Long	priority	Positive integer designating the relative priority of the DDS sample, used to determine the transmission order of pending transmissions. To use publication priorities, the DataWriter’s PUBLISH_MODE QosPolicy (DDS Extension) must be set for asynchronous publishing and the DataWriter must use a FlowController with a highest-priority first scheduling_policy. For Multi-channel DataWriters, the publication priority of a DDS sample may be used as a filter criteria for determining channel membership. For more information, see Prioritized DDS Samples.
DDS_Long	flag	Flags for the DDS sample, represented as a 32-bit integer, of which only the 16 least-significant bits are used. RTI reserves least-significant bits [0-7] for middleware-specific usage. The application can use least significant bits [8-15]. An application can inspect the flags associated with a received DDS sample by checking the flag field in The SampleInfo Structure. For details about the reserved bits see The SampleInfo Structure. Default 0 (no flags are set).
struct DDS_GUID_t	source_guid	Identifies the application logical data source associated with the sample being written.
struct DDS_GUID_t	related_source_guid	Identifies the application logical data source that is related to the sample being written.
struct DDS_GUID_t	related_reader_guid	Identifies a DataReader that is logically related to the sample that is being written.

When using the C API, a newly created variable of type DDS_WriteParams_t should be initialized by setting it to DDS_WRITEPARAMS_DEFAULT.

The write() operation also asserts liveliness on the DataWriter, the associated Publisher, and the associated DomainParticipant. It has the same effect with regards to liveliness as an explicit call to assert_liveliness(), see Asserting Liveliness and the LIVELINESS QosPolicy. Maintaining liveliness is important for DataReaders to know that the DataWriter still exists and for the proper behavior of the OWNERSHIP QosPolicy.

Blocking During a write()

The write() operation may block if the RELIABILITY QosPolicy kind is set to Reliable and the modification would cause data to be lost or cause one of the limits specified in the RESOURCE_LIMITS QosPolicy to be exceeded. Specifically, write() may block in the following situations (note that the list may not be exhaustive), even if its HISTORY QosPolicy is KEEP_LAST:

If max_samples1max_samples in is DDS_ResourceLimitsQosPolicy < max_instances, the DataWriter may block regardless of the depth field in the HISTORY QosPolicy.
If max_samples < (max_instances * depth), in the situation where the max_samples resource limit is exhausted, Connext DDS may discard DDS samples of some other instance, as long as at least one DDS sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block.
If min_send_window_size < max_samples, it is possible for the send_window_size limit to be reached before Connext DDS is allowed to discard DDS samples, in which case the DataWriter will block.

This operation may also block when using BEST_EFFORT Reliability RELIABILITY QosPolicy) and ASYNCHRONOUS Publish Mode (PUBLISH_MODE QosPolicy (DDS Extension)) QoS settings. In this case, the DataWriter will queue DDS samples until they are sent by the asynchronous publishing thread. The number of DDS samples that can be stored is determined by the HISTORY QosPolicy. If the asynchronous thread does not send DDS samples fast enough (such as when using a slow FlowController (FlowControllers (DDS Extension))), the queue may fill up. In that case, subsequent write calls will block.

If this operation does block for any of the above reasons, the RELIABILITY max_blocking_time configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DataWriter can store the modification without exceeding the limits, the operation will fail and return RETCODE_TIMEOUT.