3.3.4. DataWriter¶

A DataWriter is attached to exactly one Publisher that acts as a factory for it. Additionally, each DataWriter is bound to a single Topic since its creation. This Topic must exist prior to the creation of the DataWriter, and must be bound to the data type that the DataWriter wants to publish.

The effect of creating a new DataWriter in a Publisher for a specific Topic is to initiate a new publication with the name and data type described by the Topic.

Once the DataWriter is created, the application can inform of changes in the data value using the write() member function on the DataWriter. These changes will be transmitted to all subscriptions matched with this publication.

3.3.4.1. DataWriterQos¶

DataWriterQos controls the behavior of the DataWriter. Internally it contains the following QosPolicy objects:

QosPolicy class	Accessor/Mutator	Mutable
DurabilityQosPolicy	`durability()`	No
DurabilityServiceQosPolicy	`durability_service()`	No
DeadlineQosPolicy	`deadline()`	Yes
LatencyBudgetQosPolicy	`latency_budget()`	Yes
LivelinessQosPolicy	`liveliness()`	No
ReliabilityQosPolicy	`reliability()`	No (*)
DestinationOrderQosPolicy	`destination_order()`	No
HistoryQosPolicy	`history()`	No
ResourceLimitsQosPolicy	`resource_limits()`	No
TransportPriorityQosPolicy	`transport_priority()`	Yes
LifespanQosPolicy	`lifespan()`	Yes
UserDataQosPolicy	`user_data()`	Yes
OwnershipQosPolicy	`ownership()`	No
OwnershipStrengthQosPolicy	`ownership_strength()`	Yes
WriterDataLifecycleQosPolicy	`writer_data_lifecycle()`	Yes
PublishModeQosPolicy	`publish_mode()`	No
DataRepresentationQosPolicy	`representation()`	No
PropertyPolicyQos	`properties()`	No
RTPSReliableWriterQos	`reliable_writer_qos()`	Yes (*)
RTPSEndpointQos	`endpoint()`	No
WriterResourceLimitsQos	`writer_resource_limits()`	No
DataSharingQosPolicy	`data_sharing()`	No

The following non-consolidated property-assigned QoS apply to DataWriters:

Property name	Non-consolidated QoS
fastdds.push_mode	DataWriter operating mode QoS Policy
partitions	Endpoint Partitions

Refer to the detailed description of each QosPolicy class for more information about their usage and default values.

Note

Reliability kind (whether the publication is reliable or best effort) is not mutable. However, the max_blocking_time data member of ReliabilityQosPolicy can be modified any time.

Note

Not all data members of RTPSReliableWriterQos are mutable, please refer to RTPSReliableWriterQos for more information.

The QoS value of a previously created DataWriter can be modified using the DataWriter::set_qos() member function.

// Create a DataWriter with default DataWriterQos
DataWriter* data_writer =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DataWriterQos qos = data_writer->get_qos();

// Modify QoS attributes
// (...)

// Assign the new Qos to the object
data_writer->set_qos(qos);

3.3.4.1.1. Default DataWriterQos¶

The default DataWriterQos refers to the value returned by the get_default_datawriter_qos() member function on the Publisher instance. The special value DATAWRITER_QOS_DEFAULT can be used as QoS argument on create_datawriter() or DataWriter::set_qos() member functions to indicate that the current default DataWriterQos should be used.

When the system starts, the default DataWriterQos is equivalent to the default constructed value DataWriterQos(). The default DataWriterQos can be modified at any time using the set_default_datawriter_qos() member function on the Publisher instance. Modifying the default DataWriterQos will not affect already existing DataWriter instances.

// Get the current QoS or create a new one from scratch
DataWriterQos qos_type1 = publisher->get_default_datawriter_qos();

// Modify QoS attributes
// (...)

// Set as the new default DataWriterQos
if (publisher->set_default_datawriter_qos(qos_type1) != RETCODE_OK)
{
    // Error
    return;
}

// Create a DataWriter with the new default DataWriterQos.
DataWriter* data_writer_with_qos_type1 =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer_with_qos_type1)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DataWriterQos qos_type2;

// Modify QoS attributes
// (...)

// Set as the new default DataWriterQos
if (publisher->set_default_datawriter_qos(qos_type2) != RETCODE_OK)
{
    // Error
    return;
}

// Create a DataWriter with the new default DataWriterQos.
DataWriter* data_writer_with_qos_type2 =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer_with_qos_type2)
{
    // Error
    return;
}

// Resetting the default DataWriterQos to the original default constructed values
if (publisher->set_default_datawriter_qos(DATAWRITER_QOS_DEFAULT)
        != RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following
if (publisher->set_default_datawriter_qos(DataWriterQos())
        != RETCODE_OK)
{
    // Error
    return;
}

set_default_datawriter_qos() member function also accepts the special value DATAWRITER_QOS_DEFAULT as input argument. This will reset the current default DataWriterQos to default constructed value DataWriterQos().

// Create a custom DataWriterQos
DataWriterQos custom_qos;

// Modify QoS attributes
// (...)

// Create a DataWriter with a custom DataWriterQos
DataWriter* data_writer = publisher->create_datawriter(topic, custom_qos);
if (nullptr == data_writer)
{
    // Error
    return;
}

// Set the QoS on the DataWriter to the default
if (data_writer->set_qos(DATAWRITER_QOS_DEFAULT) != RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following:
if (data_writer->set_qos(publisher->get_default_datawriter_qos())
        != RETCODE_OK)
{
    // Error
    return;
}

Note

The value DATAWRITER_QOS_DEFAULT has different meaning depending on where it is used:

On create_datawriter() and DataWriter::set_qos() it refers to the default DataWriterQos as returned by get_default_datawriter_qos().
On set_default_datawriter_qos() it refers to the default constructed DataWriterQos().

3.3.4.2. Type support context¶

A DataWriter can be configured with a type support context that is forwarded to the TopicDataType callbacks on every write operation. This allows the type implementation to rely on per-writer information (e.g., bounded sizes)

The context must be set before enabling the DataWriter using DataWriter::set_type_support_context(). Calling this method on an already-enabled DataWriter returns RETCODE_ILLEGAL_OPERATION.

// User-defined context struct carrying per-writer configuration.
struct MyContext : public TopicDataType::Context
{
    uint32_t string_max_length = 0;
    uint32_t sequence_max_length = 0;
};

// Create a DataWriter (initially disabled, e.g. via participant QoS).
DataWriterQos writer_qos = DATAWRITER_QOS_DEFAULT;
DataWriter* writer = publisher->create_datawriter(topic, writer_qos);

// Create a context carrying per-writer configuration.
auto context = std::make_shared<MyContext>();
context->string_max_length = 512;
context->sequence_max_length = 1024;

// Set it before enabling the DataWriter.
ReturnCode_t ret = writer->set_type_support_context(context);
assert(ret == RETCODE_OK);

// Then enable the writer (e.g., by enabling its DomainParticipant).