Skip to content

iceoptions🔗

Introduction🔗

This example demonstrates what kind of quality of service options can be configured on the publisher and subscriber side. The options can be used for the typed and untyped C++ API flavors as well as the C API.

Expected Output🔗

asciicast

Code walkthrough🔗

Publisher🔗

In order to configure a publisher, we have to supply a struct of the type iox::popo::PublisherOptions as a second parameter.

historyCapacity will enable subscribers to read the last n samples e.g. in case they are started later than the publisher:

publisherOptions.historyCapacity = 10U;

Topics are automatically offered on creation of a publisher, if you want to disable that feature and control the offering yourself, do:

publisherOptions.offerOnCreate = false;

Due to the disabled offerOnCreate feature, don't forget to offer our topic:

publisher.offer();

To organize publishers inside an application, they can be associated and grouped by providing a node name. Some frameworks call nodes runnables.

publisherOptions.nodeName = "Pub_Node_With_Options";

To ensure that samples are never lost, you have the possibility to busy-wait for the subscriber when publishing. Both publisher and subscriber have to request compatible policies (SubscriberTooSlowPolicy::WAIT_FOR_SUBSCRIBER and QueueFullPolicy::BLOCK_PUBLISHER).

publisherOptions.subscriberTooSlowPolicy = iox::popo::SubscriberTooSlowPolicy::WAIT_FOR_SUBSCRIBER;

With this option set, it is possible that a slow subscriber blocks a publisher indefinitely due to the busy waiting loop. In order to be able to gracefully shutdown the application with Ctrl+C, the publisher needs to be unblocked. This is done by placing the following code in the signal handler.

iox::runtime::PoshRuntime::getInstance().shutdown();

Subscriber🔗

To configure a subscriber, we have to supply a struct of the type iox::popo::SubscriberOptions as a second parameter.

The queueCapacity parameter specifies how many samples the queue of the subscriber object can hold. If the queue would encounter an overflow, the oldest sample is released to create space for the newest one, which is then stored. The queue behaves like a circular buffer.

subscriberOptions.queueCapacity = 10U;

historyRequest will enable a subscriber to receive the last n samples on subscription e.g. in case it was started later than the publisher. The publisher needs to have its historyCapacity enabled, too.

subscriberOptions.historyRequest = 5U;

Topics are automatically subscribed on creation, if you want to disable that feature and control the subscription yourself, set subscribeOnCreate appropriately:

subscriberOptions.subscribeOnCreate = false;

Due to the disabled subscribeOnCreate feature, don't forget to subscribe to our topic:

subscriber.subscribe();

Again, for organising subscribers inside an application, a nodeName can be applied:

subscriberOptions.nodeName = "Sub_Node_With_Options";

Again, to ensure that samples are never lost, we request the publisher to busy-wait, in case of a full queue:

subscriberOptions.queueFullPolicy = iox::popo::QueueFullPolicy::BLOCK_PUBLISHER;

Check out iceoptions on GitHub