Session Management

The zenoh::Session is the main zenoh object. The instance of the session reprsents a single zenoh node in the network.

Session

class Session : public zenoh::Owned<::z_owned_session_t>

A Zenoh session.

Constructors

inline Session(Config &&config, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

Create a new Session.

Parameters:

  • config – Zenoh session Config.

  • options – options to pass to session creation operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline Session(Config &&config, const ShmClientStorage &shm_storage, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

Create a new Session with custom SHM client set.

Parameters:

  • config – Zenoh session Config.

  • shm_storage – storage with custom SHM clients.

  • options – options to pass to session creation operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

static inline Session open(Config &&config, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

A factory method equivalent to a Session constructor.

Parameters:

  • config – Zenoh session Config.

  • options – options to pass to session creation operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

Session object. In case of failure it will be return in invalid state.

static inline Session open(Config &&config, const ShmClientStorage &shm_storage, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

A factory method equivalent to a Session constructor for custom SHM clients list.

Parameters:

  • config – Zenoh session Config.

  • shm_storage – storage with custom SHM clients.

  • options – options to pass to session creation operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

Session object. In case of failure it will be return in invalid state.

Methods

inline Id get_zid() const

Get the unique identifier of the zenoh node associated to this Session.

Returns:

the unique identifier Id.

inline KeyExpr declare_keyexpr(const KeyExpr &key_expr, ZResult *err = nullptr) const

Create KeyExpr instance with numeric id registered in Session routing tables (to reduce bandwith usage).

Parameters:

  • key_expr – KeyExpr to declare.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

declared KeyExpr instance.

inline void undeclare_keyexpr(KeyExpr &&key_expr, ZResult *err = nullptr) const

Remove KeyExpr instance from Session routing table and drop KeyExpr instance.

Parameters:

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

  • key_expr – KeyExpr instance to undeclare, that was previously returned by Session::declare_keyexpr.

template<class C, class D>
inline void get(const KeyExpr &key_expr, const std::string &parameters, C &&on_reply, D &&on_drop, GetOptions &&options = GetOptions::create_default(), ZResult *err = nullptr) const

Query data from the matching queryables in the system. Replies are provided through a callback function.

Parameters:

  • key_expr – KeyExpr the key expression matching resources to query.

  • parameters – the parameters string in URL format.

  • on_reply – callable that will be called once for each received reply.

  • on_drop – callable that will be called once all replies are received.

  • options – GetOptions query options.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

template<class Channel>
inline Channel::template HandlerType<Reply> get(const KeyExpr &key_expr, const std::string &parameters, Channel channel, GetOptions &&options = GetOptions::create_default(), ZResult *err = nullptr) const

Query data from the matching queryables in the system. Replies are provided through a channel.

Template Parameters:

Channel – the type of channel used to create stream of data (see zenoh::channels::FifoChannel or zenoh::channels::RingChannel).

Parameters:

  • key_expr – the key expression matching resources to query.

  • parameters – the parameters string in URL format.

  • channel – channel instance.

  • options – query options.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

reply handler.

template<class C, class D>
inline Queryable<void> declare_queryable(const KeyExpr &key_expr, C &&on_query, D &&on_drop, QueryableOptions &&options = QueryableOptions::create_default(), ZResult *err = nullptr) const

Create a Queryable object to answer to Session::get requests.

Parameters:

  • key_expr – the key expression to match the Session::get requests.

  • on_query – the callable to handle Query requests. Will be called once for each query.

  • on_drop – the drop callable. Will be called once, when Queryable is destroyed or undeclared.

  • options – options passed to queryable declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Queryable object.

template<class C, class D>
inline void declare_background_queryable(const KeyExpr &key_expr, C &&on_query, D &&on_drop, QueryableOptions &&options = QueryableOptions::create_default(), ZResult *err = nullptr) const

Declare a background queryable. It will answer to Session::get requests, until the corresponding session is closed or destroyed.

Parameters:

  • key_expr – the key expression to match the Session::get requests.

  • on_query – the callable to handle Query requests. Will be called once for each query.

  • on_drop – the drop callable. Will be called once, when Queryable is destroyed or undeclared.

  • options – options passed to queryable declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

template<class Channel>
inline Queryable<typename Channel::template HandlerType<Query>> declare_queryable(const KeyExpr &key_expr, Channel channel, QueryableOptions &&options = QueryableOptions::create_default(), ZResult *err = nullptr) const

Create a Queryable object to answer to Session::get requests.

Template Parameters:

Channel – the type of channel used to create stream of data (see zenoh::channels::FifoChannel or zenoh::channels::RingChannel).

Parameters:

  • key_expr – the key expression to match the Session::get requests.

  • channel – an instance of channel.

  • options – options passed to queryable declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Queryable object.

template<class C, class D>
inline Subscriber<void> declare_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, SubscriberOptions &&options = SubscriberOptions::create_default(), ZResult *err = nullptr) const

Create a Subscriber object to receive data from matching Publisher objects or from Session::put and Session::delete_resource requests.

Parameters:

  • key_expr – the key expression to match the publishers.

  • on_sample – the callback that will be called for each received sample.

  • on_drop – the callback that will be called once subscriber is destroyed or undeclared.

  • options – options to pass to subscriber declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Subscriber object.

template<class C, class D>
inline void declare_background_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, SubscriberOptions &&options = SubscriberOptions::create_default(), ZResult *err = nullptr) const

Declare a a background subscriber. It will receive data from matching Publisher objects or from Session::put and Session::delete_resource requests, until the corresponding session is closed or destroyed.

Parameters:

  • key_expr – the key expression to match the publishers.

  • on_sample – the callback that will be called for each received sample.

  • on_drop – the callback that will be called once subscriber is destroyed or undeclared.

  • options – options to pass to subscriber declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

template<class Channel>
inline Subscriber<typename Channel::template HandlerType<Sample>> declare_subscriber(const KeyExpr &key_expr, Channel channel, SubscriberOptions &&options = SubscriberOptions::create_default(), ZResult *err = nullptr) const

Create a Subscriber object to receive data from matching Publisher objects or from. Session::put and Session::delete_resource requests.

Template Parameters:

Channel – the type of channel used to create stream of data (see zenoh::channels::FifoChannel or zenoh::channels::RingChannel).

Parameters:

  • key_expr – the key expression to match the publishers.

  • channel – an instance of channel.

  • options – options to pass to subscriber declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Subscriber object.

inline void delete_resource(const KeyExpr &key_expr, DeleteOptions &&options = DeleteOptions::create_default(), ZResult *err = nullptr) const

Undeclare a resource. Equivalent to Publisher::delete_resource.

Parameters:

  • key_expr – the key expression to delete the resource.

  • options – options to pass to delete operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void put(const KeyExpr &key_expr, Bytes &&payload, PutOptions &&options = PutOptions::create_default(), ZResult *err = nullptr) const

Publish data to the matching subscribers in the system. Equivalent to Publisher::put.

Parameters:

  • key_expr – the key expression to put the data.

  • payload – the data to publish.

  • options – options to pass to put operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline Publisher declare_publisher(const KeyExpr &key_expr, PublisherOptions &&options = PublisherOptions::create_default(), ZResult *err = nullptr) const

Create a Publisher object to publish data to matching Subscriber objects.

Parameters:

  • key_expr – the key expression to match the subscribers.

  • options – options passed to publisher declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Publisher object.

inline Querier declare_querier(const KeyExpr &key_expr, QuerierOptions &&options = QuerierOptions::create_default(), ZResult *err = nullptr) const

Create a Querier object to send queries to matching Queryable objects.

Parameters:

  • key_expr – the key expression to match the queryables.

  • options – options passed to querier declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Querier object.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

inline std::vector<Id> get_routers_z_id(ZResult *err = nullptr) const

Fetches the Zenoh IDs of all connected routers.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a vector of all connected router Id.

inline std::vector<Id> get_peers_z_id(ZResult *err = nullptr) const

Fetches the Zenoh IDs of all connected peers.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a vector of all connected peer Id.

inline void start_read_task(ZResult *err = nullptr)

Start a separate task to read from the network and process the messages as soon as they are received.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-pico only.

inline void stop_read_task(ZResult *err = nullptr)

Stop the read task.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-pico only.

inline void start_lease_task(ZResult *err = nullptr)

Start a separate task to handle the session lease. This task will send KeepAlive messages when needed and will close the session when the lease is expired. When operating over a multicast transport, it also periodically sends the Join messages.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-pico only.

inline void stop_lease_task(ZResult *err = nullptr)

Stop the lease task.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-pico only.

inline void read(ZResult *err = nullptr)

Triggers a single execution of reading procedure from the network and processes of any received the message.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-pico only.

inline void send_keep_alive(ZResult *err = nullptr)

Triggers a single execution of keep alive procedure. It will send KeepAlive messages when needed and will close the session when the lease is expired.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void send_join(ZResult *err = nullptr)

Triggers a single execution of join procedure: send the Join message.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline LivelinessToken liveliness_declare_token(const KeyExpr &key_expr, LivelinessDeclarationOptions &&options = LivelinessDeclarationOptions::create_default(), ZResult *err = nullptr)

Declares a liveliness token on the network.

Liveliness token subscribers on an intersecting key expression will receive a PUT sample when connectivity is achieved, and a DELETE sample if it’s lost.

Parameters:

  • key_expr – a keyexpr to declare a liveliess token for.

  • options – liveliness token declaration properties.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a LivelinessToken.

template<class C, class D>
inline Subscriber<void> liveliness_declare_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, LivelinessSubscriberOptions &&options = LivelinessSubscriberOptions::create_default(), ZResult *err = nullptr) const

Declares a subscriber on liveliness tokens that intersect key_expr.

Parameters:

  • key_expr – the key expression to subscribe to.

  • on_sample – the callable that will be called each time a liveliness token status is changed.

  • on_drop – the callable that will be called once subscriber is destroyed or undeclared.

  • options – options to pass to subscriber declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Subscriber object.

template<class C, class D>
inline void liveliness_declare_background_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, LivelinessSubscriberOptions &&options = LivelinessSubscriberOptions::create_default(), ZResult *err = nullptr) const

Declares a background subscriber on liveliness tokens that intersect key_expr. The subscriber callback will be run in the background until the corresponding session is closed or destroyed.

Parameters:

  • key_expr – the key expression to subscribe to.

  • on_sample – the callable that will be called each time a liveliness token status is changed.

  • on_drop – the callable that will be called once subscriber is destroyed or undeclared.

  • options – options to pass to subscriber declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-c only.

template<class Channel>
inline Subscriber<typename Channel::template HandlerType<Sample>> liveliness_declare_subscriber(const KeyExpr &key_expr, Channel channel, LivelinessSubscriberOptions &&options = LivelinessSubscriberOptions::create_default(), ZResult *err = nullptr) const

Declare a subscriber on liveliness tokens that intersect key_expr.

Template Parameters:

Channel – the type of channel used to create stream of data (see zenoh::channels::FifoChannel or zenoh::channels::RingChannel).

Parameters:

  • key_expr – the key expression to subscribe to.

  • channel – an instance of channel.

  • options – options to pass to subscriber declaration.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a Subscriber object.

template<class C, class D>
inline void liveliness_get(const KeyExpr &key_expr, C &&on_reply, D &&on_drop, LivelinessGetOptions &&options = LivelinessGetOptions::create_default(), ZResult *err = nullptr) const

Query liveliness tokens currently on the network with a key expression intersecting with key_expr.

Parameters:

  • key_expr – the key expression to query liveliness tokens for.

  • on_reply – the callable that will be called for each received reply.

  • on_drop – the callable that will be called once all replies are received.

  • options – additional options for the liveliness get operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

template<class Channel>
inline Channel::template HandlerType<Reply> liveliness_get(const KeyExpr &key_expr, Channel channel, LivelinessGetOptions &&options = LivelinessGetOptions::create_default(), ZResult *err = nullptr) const

Query liveliness tokens currently on the network with a key expression intersecting with key_expr.

Template Parameters:

Channel – the type of channel used to create stream of data (see zenoh::channels::FifoChannel or zenoh::channels::RingChannel).

Parameters:

  • key_expr – the key expression to query liveliness tokens for.

  • channel – channel instance.

  • options – additional options for the liveliness get operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

reply handler.

inline Timestamp new_timestamp(ZResult *err = nullptr)

Create Timestamp from session id.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void close(SessionCloseOptions &&options = SessionCloseOptions::create_default(), ZResult *err = nullptr)

Close the session and undeclare all not yet undeclared Subscriber and Queryable callbacks. After this, all calls to corresponding session (or session entity) methods will fail. It still possible though to process any already received messages using Subscriber or Queryable handlers (but not reply to them).

Parameters:

  • options – options to pass to close operation.

  • err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline bool is_closed() const

Check if session is closed.

Returns:

true if session is closed, false otherwise.

template<class Ext = zenoh::ext::SessionExt>
inline Ext ext() const

Get access to extension functionality.

Template Parameters:

Ext – Session interface extension.

Returns:

Session interface extension providing access to non-core Zenoh functionality.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

struct DeleteOptions

Options to be passed to delete_resource operation.

Fields

Priority priority = Z_PRIORITY_DEFAULT

The priority of the delete message.

CongestionControl congestion_control = ::z_internal_congestion_control_default_push()

The congestion control to apply when routing delete message.

bool is_express = false

Whether Zenoh will NOT wait to batch delete message with others to reduce the bandwith.

Reliability reliability = z_reliability_default()

The delete operation reliability.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<Timestamp> timestamp = {}

the timestamp of this message.

Methods

static inline DeleteOptions create_default()

Create default option settings.

struct GetOptions

Options passed to the Session::get operation.

Fields

QueryTarget target = QueryTarget::Z_QUERY_TARGET_BEST_MATCHING

The Queryables that should be target of the query.

QueryConsolidation consolidation = QueryConsolidation()

The replies consolidation strategy to apply on replies to the query.

Priority priority = Z_PRIORITY_DEFAULT

The priority of the get message.

CongestionControl congestion_control = ::z_internal_congestion_control_default_request()

The congestion control to apply when routing get message.

bool is_express = false

Whether Zenoh will NOT wait to batch get message with others to reduce the bandwith.

std::optional<Bytes> payload = {}

An optional payload of the query.

std::optional<Encoding> encoding = {}

An optional encoding of the query payload and/or attachment.

std::optional<SourceInfo> source_info = {}

The source info for the query.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

ReplyKeyExpr accept_replies = ::zc_reply_keyexpr_default()

The accepted replies for the query.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Locality allowed_destination = ::zc_locality_default()

Allowed destination.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<Bytes> attachment = {}

An optional attachment to the query.

uint64_t timeout_ms = 0

The timeout for the query in milliseconds. 0 means default query timeout from zenoh configuration.

Methods

static inline GetOptions create_default()

Create default option settings.

struct LivelinessDeclarationOptions

Options to pass to Session::liveliness_declare_token.

Methods

static inline LivelinessDeclarationOptions create_default()

Create default option settings.

struct LivelinessGetOptions

Options to pass to Session::liveliness_get.

Fields

uint64_t timeout_ms = 10000

The timeout for the query in milliseconds.

Methods

static inline LivelinessGetOptions create_default()

Create default option settings.

struct LivelinessSubscriberOptions

Options to pass to Session::liveliness_declare_subscriber.

Fields

bool history = false

If true, subscriber will receive the state change notifications for liveliness tokens that were declared before its declaration.

Methods

static inline LivelinessSubscriberOptions create_default()

Create default option settings.

struct PublisherOptions

Options to be passed when declaring a Publisher.

Fields

CongestionControl congestion_control = ::z_internal_congestion_control_default_push()

The congestion control to apply when routing messages from this publisher.

Priority priority = Z_PRIORITY_DEFAULT

The priority of messages from this publisher.

bool is_express = false

If true, Zenoh will not wait to batch this message with others to reduce the bandwith.

Reliability reliability = z_reliability_default()

The publisher reliability.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Locality allowed_destination = ::zc_locality_default()

Allowed destination.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<Encoding> encoding = {}

Default encoding to use for Publisher::put.

Methods

static inline PublisherOptions create_default()

Create default option settings.

struct PutOptions

Options passed to the Session::put operation.

Fields

Priority priority = Z_PRIORITY_DEFAULT

The priority of this message.

CongestionControl congestion_control = ::z_internal_congestion_control_default_push()

The congestion control to apply when routing this message.

bool is_express = false

Whether Zenoh will NOT wait to batch this message with others to reduce the bandwith.

Locality allowed_destination = ::zc_locality_default()

Allowed destination.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<Timestamp> timestamp = {}

the timestamp of this message.

std::optional<Encoding> encoding = {}

An optional encoding of the message payload and/or attachment.

Reliability reliability = z_reliability_default()

The put operation reliability.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<SourceInfo> source_info = {}

The source info of this message.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<Bytes> attachment = {}

An optional attachment to the message.

Methods

static inline PutOptions create_default()

Create default option settings.

struct QuerierOptions

Options to be passed when declaring a Querier.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Fields

QueryTarget target = QueryTarget::Z_QUERY_TARGET_BEST_MATCHING

The Queryables that should be target of the querier queries.

QueryConsolidation consolidation = QueryConsolidation()

The replies consolidation strategy to apply on replies to the querier queries.

Priority priority = Z_PRIORITY_DEFAULT

The priority of the querier queries.

CongestionControl congestion_control = ::z_internal_congestion_control_default_request()

The congestion control to apply when routing querier queries.

bool is_express = false

Whether Zenoh will NOT wait to batch querier queries with other messages to reduce the bandwith.

ReplyKeyExpr accept_replies = ::zc_reply_keyexpr_default()

The accepted replies for the querier queries.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Locality allowed_destination = ::zc_locality_default()

Allowed destination for querier queries.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

uint64_t timeout_ms = 0

The timeout for the querier queries in milliseconds. 0 means default query timeout from zenoh configuration.

Methods

static inline QuerierOptions create_default()

Create default option settings.

struct QueryableOptions

Options to be passed when declaring a Queryable

Fields

bool complete = false

The completeness of the Queryable.

Locality allowed_origin = ::zc_locality_default()

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release. Restrict the matching requests that will be received by this Queryable to the ones that have the compatible allowed_destination.

Methods

static inline QueryableOptions create_default()

Create default option settings.

struct SessionCloseOptions

Options to be passed when closing a Session.

struct SessionOptions

Options to be passed when opening a Session.

Fields

bool start_background_tasks = true

If true, start background threads which handle the network traffic. If false, the threads should be called manually with Session::start_read_task and Session::start_lease_task or methods Session::read, Session::send_keep_alive and Session::send_join should be called in loop.

Note

Zenoh-pico only.

struct SubscriberOptions

Options to be passed when declaring a Subscriber.

Fields

Locality allowed_origin = ::zc_locality_default()

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release. Restrict the matching publications that will be received by this Subscribers to the ones that have the compatible allowed_destination.

Methods

static inline SubscriberOptions create_default()

Create default option settings.