From 2fab3d61e28a547389571de9e4c4ca42059e3a4a Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Thu, 12 Sep 2024 11:21:32 +0200 Subject: [PATCH 1/3] docs: add undeclaration on drop documentation for Rust --- content/docs/migration_1.0/Rust.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/content/docs/migration_1.0/Rust.md b/content/docs/migration_1.0/Rust.md index 1821adea..60fc35f5 100644 --- a/content/docs/migration_1.0/Rust.md +++ b/content/docs/migration_1.0/Rust.md @@ -107,6 +107,36 @@ session.close().await.unwrap(); subscriber_task.await.unwrap() ``` +## Callbacks run in background until session is closed + +Session entities, e.g. subscribers, declared with callbacks are no more undeclared when they are dropped; there is no more need to keep a variable around when the intent is to have it run until the session is closed. + +```rust +let session = zenoh::open(zenoh::config::peer()).await. unwrap(); +session + .declare_subscriber("key/ expression") + .callback(|sample| { println!("Received: {} {:?}", sample. key_expr(), sample. payload()) }) + .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::peer()).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)`. You should rarely need to call this method directly however.* + ## Value is gone, long live ZBytes We have replaced `Value` with `ZBytes` and `Encoding` , and added a number of conversion implementations such that user structs can be serialized into `ZBytes`, sent via Zenoh, and de-serialized from `ZBytes` with ease. From 77df3afed6d4442f31518aec56d93ca1ea5b4060 Mon Sep 17 00:00:00 2001 From: Joseph Perez Date: Thu, 12 Sep 2024 14:39:37 +0200 Subject: [PATCH 2/3] Update content/docs/migration_1.0/Rust.md Co-authored-by: Charles Schleich --- 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 60fc35f5..ddc5d30e 100644 --- a/content/docs/migration_1.0/Rust.md +++ b/content/docs/migration_1.0/Rust.md @@ -109,7 +109,7 @@ subscriber_task.await.unwrap() ## Callbacks run in background until session is closed -Session entities, e.g. subscribers, declared with callbacks are no more undeclared when they are dropped; there is no more need to keep a variable around when the intent is to have it run until the 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. ```rust let session = zenoh::open(zenoh::config::peer()).await. unwrap(); From 3deb9f3cf16dffd4d0e97ea10552c64dc299a4d2 Mon Sep 17 00:00:00 2001 From: Luca Cominardi Date: Thu, 12 Sep 2024 17:33:40 +0200 Subject: [PATCH 3/3] Apply suggestions from code review --- content/docs/migration_1.0/Rust.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/docs/migration_1.0/Rust.md b/content/docs/migration_1.0/Rust.md index ddc5d30e..b3aa1342 100644 --- a/content/docs/migration_1.0/Rust.md +++ b/content/docs/migration_1.0/Rust.md @@ -112,7 +112,7 @@ subscriber_task.await.unwrap() 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. ```rust -let session = zenoh::open(zenoh::config::peer()).await. unwrap(); +let session = zenoh::open(zenoh::config::default()).await.unwrap(); session .declare_subscriber("key/ expression") .callback(|sample| { println!("Received: {} {:?}", sample. key_expr(), sample. payload()) }) @@ -125,7 +125,7 @@ session 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::peer()).await. unwrap(); +let session = zenoh::open(zenoh::config::default()).await.unwrap(); let subscriber = session .declare_subscriber("key/ expression") // annotation needed @@ -135,7 +135,8 @@ let subscriber = session // 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)`. You should rarely need to call this method directly however.* +*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