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🔗
Code walkthrough🔗
Info
This example describes a single publisher scenario.
Publisher🔗
In order to configure a publisher, we have to supply a struct of the type iox::popo::PublisherOptions as a second parameter.
iox::popo::Publisher<RadarObject> publisher({"Radar", "FrontLeft", "Object"}, publisherOptions);
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 (ConsumerTooSlowPolicy::WAIT_FOR_CONSUMER and
QueueFullPolicy::BLOCK_PRODUCER).
publisherOptions.subscriberTooSlowPolicy = iox::popo::ConsumerTooSlowPolicy::WAIT_FOR_CONSUMER;
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 shut down the application with Ctrl+C, the publisher needs to be unblocked.
To achieve this, we publish the data in a background thread so that we can initiate the shutdown
of the runtime:
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.
iox::popo::Subscriber<RadarObject> subscriber({"Radar", "FrontLeft", "Object"}, subscriberOptions);
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 of matching publishers on subscription e.g. in case it was started later than the publisher.
If the publisher does not have a sufficient historyCapacity (smaller than historyRequest), it will still be connected but we will not be able to
receive the requested amount of historical data (if it was available). Instead we will receive the largest amount of historical sample
the publisher has available, i.e. best-effort. In particular we will be connected to a publisher with historyCapacity = 0.
If we want to enforce the contract that the publisher needs to support a historyCapacity, we can do so by setting requirePublisherHistorySupport
to true. In this case, the subscriber will only connect if the publisher history support is at least 1, i.e. historyCapacity > 0.
By default this is set to false and best-effort behavior is used.
Warning
In case of n:m communication, the history feature will not provide the overall last n samples based on delivery point in time! For more information about this limitation see the QoS article.
subscriberOptions.historyRequest = 5U;
subscriberOptions.requiresPublisherHistorySupport = false;
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";
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_PRODUCER;