From 91b52a3e552b37b6c7c30fdaadff10e87e65db7b Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Thu, 10 Oct 2024 10:37:08 +0200 Subject: [PATCH 1/4] docs: update migration guide for background semantic --- content/docs/migration_1.0/Python.md | 7 ++++--- content/docs/migration_1.0/Rust.md | 29 +++++++--------------------- 2 files changed, 11 insertions(+), 25 deletions(-) diff --git a/content/docs/migration_1.0/Python.md b/content/docs/migration_1.0/Python.md index e4aee639..f62deddd 100644 --- a/content/docs/migration_1.0/Python.md +++ b/content/docs/migration_1.0/Python.md @@ -29,12 +29,13 @@ with session.declare_subscriber("my/keyexpr") as subscriber: # `subscriber.undeclare()` will be called at the end of the block` ``` -In previous version, it was necessary to keep a variable in the scope for a subscriber/queryable declared with a callback. This constraint has been lifted, and it's now possible to declare and forget an entity with a callback; in that case, the entity will keep living in background, until the session is closed. +In previous version, it was necessary to keep a variable in the scope for a subscriber/queryable declared with a callback. This constraint has been lifted, and it's now possible to declare a "background" entity; this entity will keep living in background, having its callback executed until the session is closed. ```python import zenoh with zenoh.open(zenoh.Config()) as session: - session.declare_subscriber("my/keyepxr", lambda s: print(s)) + # no need to declare a variable + session.declare_subscriber("my/keyepxr", lambda s: print(s), background=True) sleep(10) # subscriber stays in background and its callback can be called # `session.close()` will be called at the end of the block, and it will undeclare the subscriber ``` @@ -81,7 +82,7 @@ NOTE: ⚠️ Serialization of `bytes` is not the same as passing `bytes` to `ZBy Zenoh does not impose any encoding requirement on the user, nor does it operate on it. It can be thought of as optional metadata, carried over by Zenoh in such a way that the end user’s application may perform different operations based on encoding. -NOTE: ⚠️ The encoding is no longer automatically deduced from the payload type. +NOTE: ⚠️ The encoding is no longer automatically inferred from the payload type. ```python session.put(json.dumps({"key", "value"}), encoding=Encoding.APPLICATION_JSON) diff --git a/content/docs/migration_1.0/Rust.md b/content/docs/migration_1.0/Rust.md index 1a9b9b83..b4eba7b0 100644 --- a/content/docs/migration_1.0/Rust.md +++ b/content/docs/migration_1.0/Rust.md @@ -90,7 +90,7 @@ The session is now closed automatically when the last `Session` instance is drop Subscriber and queryable of a closed session will no longer receive data; trying to call `Session::get`, `Session::put` or `Publisher::put` will result in an error. Closing session on the fly may save bandwidth on the wire, as it avoids propagating the undeclaration of remaining entities like subscribers/queryables/etc. ```rust -let session = zenoh::open(zenoh::config::peer()).await.unwrap(); +let session = zenoh::open(config).await.unwrap(); let subscriber = session .declare_subscriber("key/expression") .await @@ -111,38 +111,23 @@ subscriber_task.await.unwrap() ## Callbacks run in background until session is closed -Session entities, e.g. subscribers, declared with callbacks are no longer undeclared when they are dropped; there is no longer need to keep a reference to an entity when the intent is to have it run until the session is closed. +It is now possible to declare "background" entity, e.g. subscribers, which have their callback called until the session is closed. So it is no longer needed to keep a dummy variable in scope when the intent is to have an entity living for the rest of the program. ```rust -let session = zenoh::open(zenoh::config::default()).await.unwrap(); +let session = zenoh::open(config).await.unwrap(); session .declare_subscriber("key/ expression") .callback(|sample| { println!("Received: {} {:?}", sample. key_expr(), sample. payload()) }) + .background() // declare the subscriber in background .await .unwrap(); // subscriber run in background until the session is closed // no need to keep a variable around ``` -If you still want the entity to be undeclared when dropped, you can simply use `with` instead of `callback`; it may just require you to annotate the callback, as type inference is not as good as with `callback` method. - -```rust -let session = zenoh::open(zenoh::config::default()).await.unwrap(); -let subscriber = session - .declare_subscriber("key/ expression") - // annotation needed - .with(|sample: Sample| { println!("Received: {} {:?}", sample. key_expr(), sample. payload()) }) - .await - .unwrap(); -// subscriber is undeclared when dropped -``` - -*Going into details, a new method `undeclare_on_drop(bool)` – default to `true`, has been added to the builders, and `callback(cb)` is now simply a shortcut to `with(cb).undeclare_on_drop(false)`. -However, the normal user would rarely need to call this method directly.* - ## Value is gone, long live ZBytes -`Value` has been split into `ZBytes` and `Encoding`. `put` and other operations now require a `ZBytes` payload, and builders accept an optional `Encoding` parameter. The encoding is no longer automatically deduced from the payload type. +`Value` has been split into `ZBytes` and `Encoding`. `put` and other operations now require a `ZBytes` payload, and builders accept an optional `Encoding` parameter. The encoding is no longer automatically inferred from the payload type. `ZBytes` is a raw bytes container, which can also contain non-contiguous regions of memory. It can be created directly from raw bytes/strings using `ZBytes::from`. The bytes can be retrieved using `ZBytes::to_bytes`, which returns a `Cow<[u8]>`, as a copy may have to be done if the underlying bytes are not contiguous. @@ -391,7 +376,7 @@ let subscriber = session .unwrap(); ``` -⚠️ Note: We **no longer** support **Pull** mode in Zenoh +⚠️ Note: We **no longer** support **Pull** mode in Zenoh To get the same behavior of a Zenoh 0.11.0 `PullSubscriber`, please make use of a `RingChannel` an example of this is illustrated in `z_pull.rs`. @@ -410,7 +395,7 @@ let timestamp : Timestamp = zenoh::time::new_reception_timestamp(); - Zenoh 1.0.0 ```rust -let session: Session = zenoh::open(); +let session: Session = zenoh::open(config); // If the `timestamping` configuration is disabled, this call will return `None`. let timestamp: Option = session::new_timestamp(); ``` From 7d8f5d7bc53d5f203feb1e2b5aa5b01b5532b50c Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Fri, 11 Oct 2024 11:23:03 +0200 Subject: [PATCH 2/4] Update content/docs/migration_1.0/Rust.md Co-authored-by: oteffahi <70609372+oteffahi@users.noreply.github.com> --- content/docs/migration_1.0/Rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/migration_1.0/Rust.md b/content/docs/migration_1.0/Rust.md index b4eba7b0..073167ba 100644 --- a/content/docs/migration_1.0/Rust.md +++ b/content/docs/migration_1.0/Rust.md @@ -111,7 +111,7 @@ subscriber_task.await.unwrap() ## Callbacks run in background until session is closed -It is now possible to declare "background" entity, e.g. subscribers, which have their callback called until the session is closed. So it is no longer needed to keep a dummy variable in scope when the intent is to have an entity living for the rest of the program. +It is now possible to declare "background" entities, e.g. subscribers, which have their callback called until the session is closed. So it is no longer needed to keep a dummy variable in scope when the intent is to have an entity living for the rest of the program. ```rust let session = zenoh::open(config).await.unwrap(); From 33ed9574a2b76bcf9574b8ae72758e603a79ccdc Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Fri, 11 Oct 2024 11:23:10 +0200 Subject: [PATCH 3/4] Update content/docs/migration_1.0/Rust.md Co-authored-by: oteffahi <70609372+oteffahi@users.noreply.github.com> --- content/docs/migration_1.0/Rust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/migration_1.0/Rust.md b/content/docs/migration_1.0/Rust.md index 073167ba..3d9bc69e 100644 --- a/content/docs/migration_1.0/Rust.md +++ b/content/docs/migration_1.0/Rust.md @@ -121,7 +121,7 @@ session .background() // declare the subscriber in background .await .unwrap(); -// subscriber run in background until the session is closed +// subscriber runs in background until the session is closed // no need to keep a variable around ``` From 33680aa0ee0eec9065cf32e9f28364020c02f2d7 Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Fri, 11 Oct 2024 11:23:32 +0200 Subject: [PATCH 4/4] Update content/docs/migration_1.0/Python.md Co-authored-by: oteffahi <70609372+oteffahi@users.noreply.github.com> --- content/docs/migration_1.0/Python.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/docs/migration_1.0/Python.md b/content/docs/migration_1.0/Python.md index f62deddd..1fb331a4 100644 --- a/content/docs/migration_1.0/Python.md +++ b/content/docs/migration_1.0/Python.md @@ -37,7 +37,8 @@ with zenoh.open(zenoh.Config()) as session: # no need to declare a variable session.declare_subscriber("my/keyepxr", lambda s: print(s), background=True) sleep(10) # subscriber stays in background and its callback can be called - # `session.close()` will be called at the end of the block, and it will undeclare the subscriber + # `session.close()` will be called at the end of the block, + # and it will undeclare the subscriber ``` ## Value is gone, long live ZBytes