3.5.3. Topic

A Topic is a specialization of the broader concept of TopicDescription. A Topic represents a single data flow between Publisher and Subscriber, providing:

  • The name to identify the data flow.

  • The data type that is transmitted on that flow.

  • The QoS values related to the data itself.

The behavior of the Topic can be modified with the QoS values specified on TopicQos. The QoS values can be set at the creation of the Topic, or modified later with the Topic::set_qos() member function.

Like other Entities, Topic accepts a Listener that will be notified of status changes on the Topic.

Please refer to Creating a Topic for more information about how to create a Topic.

3.5.3.1. TopicQos

TopicQos controls the behavior of the Topic. Internally it contains the following QosPolicy objects:

QosPolicy class

Accessor

Mutable

TopicDataQosPolicy

topic_data()

Yes

DurabilityQosPolicy

durability()

Yes

DurabilityServiceQosPolicy

durability_service()

Yes

DeadlineQosPolicy

deadline()

Yes

LatencyBudgetQosPolicy

latency_budget()

Yes

LivelinessQosPolicy

liveliness()

Yes

ReliabilityQosPolicy

reliability()

Yes

DestinationOrderQosPolicy

destination_order()

Yes

HistoryQosPolicy

history()

Yes

ResourceLimitsQosPolicy

resource_limits()

Yes

TransportPriorityQosPolicy

transport_priority()

Yes

LifespanQosPolicy

lifespan()

Yes

OwnershipQosPolicy

ownership()

Yes

DataRepresentationQosPolicy

representation()

Yes

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

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

// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Create a Topic with default TopicQos
Topic* topic =
        participant->create_topic("TopicName", "DataTypeName", TOPIC_QOS_DEFAULT);
if (nullptr == topic)
{
    // Error
    return;
}

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

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

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

3.5.3.1.1. Default TopicQos

The default TopicQos refers to the value returned by the get_default_topic_qos() member function on the DomainParticipant instance. The special value TOPIC_QOS_DEFAULT can be used as QoS argument on create_topic() or Topic::set_qos() member functions to indicate that the current default TopicQos should be used.

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

// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
TopicQos qos_type1 = participant->get_default_topic_qos();

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

// Set as the new default TopicQos
if (participant->set_default_topic_qos(qos_type1) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// Create a Topic with the new default TopicQos.
Topic* topic_with_qos_type1 =
        participant->create_topic("TopicName", "DataTypeName", TOPIC_QOS_DEFAULT);
if (nullptr == topic_with_qos_type1)
{
    // Error
    return;
}

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

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

// Set as the new default TopicQos
if (participant->set_default_topic_qos(qos_type2) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// Create a Topic with the new default TopicQos.
Topic* topic_with_qos_type2 =
        participant->create_topic("TopicName", "DataTypeName", TOPIC_QOS_DEFAULT);
if (nullptr == topic_with_qos_type2)
{
    // Error
    return;
}

// Resetting the default TopicQos to the original default constructed values
if (participant->set_default_topic_qos(TOPIC_QOS_DEFAULT)
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following
if (participant->set_default_topic_qos(TopicQos())
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

get_default_topic_qos() member function also accepts the value TOPIC_QOS_DEFAULT as input argument. This will reset the current default TopicQos to default constructed value TopicQos().

// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Create a custom TopicQos
TopicQos custom_qos;

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

// Create a topic with a custom TopicQos
Topic* topic = participant->create_topic("TopicName", "DataTypeName", custom_qos);
if (nullptr == topic)
{
    // Error
    return;
}

// Set the QoS on the topic to the default
if (topic->set_qos(TOPIC_QOS_DEFAULT) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following:
if (topic->set_qos(participant->get_default_topic_qos())
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

Note

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