Struct Session

pub struct Session(/* private fields */);

The entrypoint of the zenoh API.

Zenoh session is instantiated using zenoh::open and it can be used to declare various entities like publishers, subscribers, or querybables, as well as issuing queries.

Session is an Arc-like type, it can be cloned, and it is closed when the last instance is dropped (see Session::close).

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
session.put("key/expression", "value").await.unwrap();

Implementations

impl Session

pub fn zid(&self) -> ZenohId

Returns the identifier of the current session. zid() is a convenient shortcut. See Session::info() and SessionInfo::zid() for more details.

pub fn close(&self) -> CloseBuilder<Self>

Close the zenoh Session.

Every subscriber and queryable declared will stop receiving data, and further attempt to publish or query with the session or publishers will result in an error. Undeclaring an entity after session closing is a no-op. Session state can be checked with Session::is_closed.

Session are automatically closed when all its instances are dropped, same as Arc. You may still want to use this function to handle errors or close the session asynchronously.
Closing the session can also save bandwidth, as it avoids propagating the undeclaration of the remaining entities.

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let subscriber = session
    .declare_subscriber("key/expression")
    .await
    .unwrap();
let subscriber_task = tokio::spawn(async move {
    while let Ok(sample) = subscriber.recv_async().await {
        println!("Received: {} {:?}", sample.key_expr(), sample.payload());
    }
});
session.close().await.unwrap();
// subscriber task will end as `subscriber.recv_async()` will return `Err`
// subscriber undeclaration has not been sent on the wire
subscriber_task.await.unwrap();

pub fn is_closed(&self) -> bool

Check if the session has been closed.

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
assert!(!session.is_closed());
session.close().await.unwrap();
assert!(session.is_closed());

pub fn undeclare<'a, T>(&'a self, decl: T) -> impl Resolve<ZResult<()>> + 'a

where T: Undeclarable<&'a Session> + 'a,

pub fn config(&self) -> &Notifier<Config>

Available on crate feature unstable only.

Get the current configuration of the zenoh Session.

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

The returned configuration Notifier can be used to read the current zenoh configuration through the get function or modify the zenoh configuration through the insert, or insert_json5 function.

Examples

Read current zenoh configuration

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let peers = session.config().get("connect/endpoints").unwrap();

Modify current zenoh configuration

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let _ = session.config().insert_json5("connect/endpoints", r#"["tcp/127.0.0.1/7447"]"#);

pub fn new_timestamp(&self) -> Timestamp

Get a new Timestamp from a Zenoh Session.

The returned timestamp has the current time, with the Session’s runtime ZenohId.

Examples

Read current zenoh configuration

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let timestamp = session.new_timestamp();

impl Session

pub fn info(&self) -> SessionInfo

Get information about the zenoh Session.

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let info = session.info();

pub fn declare_subscriber<'b, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, ) -> SubscriberBuilder<'_, 'b, DefaultHandler>

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>,

Create a Subscriber for the given key expression.

Arguments

• key_expr - The resourkey expression to subscribe to

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let subscriber = session.declare_subscriber("key/expression")
    .await
    .unwrap();
tokio::task::spawn(async move {
    while let Ok(sample) = subscriber.recv_async().await {
        println!("Received: {:?}", sample);
    }
}).await;

pub fn declare_queryable<'b, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, ) -> QueryableBuilder<'_, 'b, DefaultHandler>

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>,

Create a Queryable for the given key expression.

Arguments

• key_expr - The key expression matching the queries the Queryable will reply to

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let queryable = session.declare_queryable("key/expression")
    .await
    .unwrap();
tokio::task::spawn(async move {
    while let Ok(query) = queryable.recv_async().await {
        query.reply(
            "key/expression",
            "value",
        ).await.unwrap();
    }
}).await;

pub fn declare_publisher<'b, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, ) -> PublisherBuilder<'_, 'b>

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>,

Create a Publisher for the given key expression.

Arguments

• key_expr - The key expression matching resources to write

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let publisher = session.declare_publisher("key/expression")
    .await
    .unwrap();
publisher.put("value").await.unwrap();

pub fn declare_querier<'b, TryIntoKeyExpr>( &self, key_expr: TryIntoKeyExpr, ) -> QuerierBuilder<'_, 'b>

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>,

Available on crate feature unstable only.

Create a Querier for the given key expression.

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

Arguments

• key_expr - The key expression matching resources to query

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let querier = session.declare_querier("key/expression")
    .await
    .unwrap();
let replies = querier.get().await.unwrap();

pub fn liveliness(&self) -> Liveliness<'_>

Obtain a Liveliness struct tied to this Zenoh Session.

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let liveliness = session
    .liveliness()
    .declare_token("key/expression")
    .await
    .unwrap();

impl Session

pub fn declare_keyexpr<'a, 'b: 'a, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, ) -> impl Resolve<ZResult<KeyExpr<'b>>> + 'a

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>,

Informs Zenoh that you intend to use key_expr multiple times and that it should optimize its transmission.

The returned KeyExpr’s internal structure may differ from what you would have obtained through a simple key_expr.try_into(), to save time on detecting the optimizations that have been associated with it.

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let key_expr = session.declare_keyexpr("key/expression").await.unwrap();

pub fn put<'a, 'b: 'a, TryIntoKeyExpr, IntoZBytes>( &'a self, key_expr: TryIntoKeyExpr, payload: IntoZBytes, ) -> SessionPutBuilder<'a, 'b>

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>, IntoZBytes: Into<ZBytes>,

Put data.

Arguments

• key_expr - Key expression matching the resources to put
• payload - The payload to put

Examples

use zenoh::bytes::Encoding;

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
session
    .put("key/expression", "payload")
    .encoding(Encoding::TEXT_PLAIN)
    .await
    .unwrap();

pub fn delete<'a, 'b: 'a, TryIntoKeyExpr>( &'a self, key_expr: TryIntoKeyExpr, ) -> SessionDeleteBuilder<'a, 'b>

where TryIntoKeyExpr: TryInto<KeyExpr<'b>>, <TryIntoKeyExpr as TryInto<KeyExpr<'b>>>::Error: Into<Error>,

Delete data.

Arguments

• key_expr - Key expression matching the resources to delete

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
session.delete("key/expression").await.unwrap();

pub fn get<'a, 'b: 'a, TryIntoSelector>( &'a self, selector: TryIntoSelector, ) -> SessionGetBuilder<'a, 'b, DefaultHandler>

where TryIntoSelector: TryInto<Selector<'b>>, <TryIntoSelector as TryInto<Selector<'b>>>::Error: Into<Error>,

Query data from the matching queryables in the system.

Unless explicitly requested via accept_replies, replies are guaranteed to have key expressions that match the requested selector.

Arguments

• selector - The selection of resources to query

Examples

let session = zenoh::open(zenoh::Config::default()).await.unwrap();
let replies = session.get("key/expression").await.unwrap();
while let Ok(reply) = replies.recv_async().await {
    println!(">> Received {:?}", reply.result());
}

Trait Implementations

impl Clone for Session

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Session

fn drop(&mut self)

Executes the destructor for this type.