Background declarations (#749)

* remove z_undeclare_subscriber/publisher/queryable/publication_cache/querying_subscriber and zc_publisher_matching_listener_undeclare - since they had the same signature and effect as corresponding drop functions;
make z(e)_subscriber/publisher/queryable/querying_subscriber_drop and zc_publisher_matching_listener_drop automatically undeclare corresponding entities;
add z(e)_declare_background_subscriber/queryable/querying_subscriber, zc_publisher_matching_listener_declare_background and  zc_liveliness_declare_background_subscriber functions, that do not return an entity, but rather register the corresponding callbacks until the session is closed/dropped;

* examples update

* clippy fix

* fix tests and examples

* rename z_declare_xxx functions to z_xxx_declare

docs/api.rst

@@ -577,10 +577,9 @@ Functions
 .. doxygenfunction:: z_put
 .. doxygenfunction:: z_delete
 
-.. doxygenfunction:: z_declare_publisher
+.. doxygenfunction:: z_publisher_declare
 .. doxygenfunction:: z_publisher_put
 .. doxygenfunction:: z_publisher_delete
-.. doxygenfunction:: z_undeclare_publisher
 .. doxygenfunction:: z_publisher_keyexpr
 .. doxygenfunction:: z_publisher_id
 
@@ -602,7 +601,9 @@ Functions
 
 .. doxygenfunction:: zc_publisher_get_matching_status
 .. doxygenfunction:: zc_publisher_matching_listener_declare
-.. doxygenfunction:: zc_publisher_matching_listener_undeclare
+.. doxygenfunction:: zc_publisher_matching_listener_declare_background
+
+.. doxygenfunction:: zc_publisher_matching_listener_drop
 
 Subscription
 ============
@@ -627,8 +628,8 @@ Types
 Functions
 ---------
 
-.. doxygenfunction:: z_declare_subscriber
-.. doxygenfunction:: z_undeclare_subscriber
+.. doxygenfunction:: z_subscriber_declare
+.. doxygenfunction:: z_subscriber_declare_background
 .. doxygenfunction:: z_subscriber_keyexpr
 
 .. doxygenfunction:: z_subscriber_drop
@@ -686,7 +687,7 @@ Types
 Functions
 ---------
 .. doxygenfunction:: z_declare_queryable
-.. doxygenfunction:: z_undeclare_queryable
+.. doxygenfunction:: z_queryable_declare_background
 .. doxygenfunction:: z_queryable_id
 
 .. doxygenfunction:: z_queryable_options_default
@@ -835,7 +836,8 @@ Types
 
 Functions
 ---------
-.. doxygenfunction:: zc_liveliness_declare_subscriber
+.. doxygenfunction:: zc_liveliness_subscriber_declare
+.. doxygenfunction:: zc_liveliness_subscriber_declare_background
 .. doxygenfunction:: zc_liveliness_get
 
 .. doxygenfunction:: zc_liveliness_declare_token
@@ -862,8 +864,7 @@ Types
 Functions
 ---------
 
-.. doxygenfunction:: ze_declare_publication_cache
-.. doxygenfunction:: ze_undeclare_publication_cache
+.. doxygenfunction:: ze_publication_cache_declare
 
 .. doxygenfunction:: ze_publication_cache_drop
 .. doxygenfunction:: ze_publication_cache_loan
@@ -886,8 +887,8 @@ Types
 Functions
 ---------
 
-.. doxygenfunction:: ze_declare_querying_subscriber
-.. doxygenfunction:: ze_undeclare_querying_subscriber
+.. doxygenfunction:: ze_querying_subscriber_declare
+.. doxygenfunction:: ze_querying_subscriber_declare_background
 .. doxygenfunction:: ze_querying_subscriber_get
 
 .. doxygenfunction:: ze_querying_subscriber_drop

docs/examples.rst

@@ -81,7 +81,7 @@ Subscribe
       z_view_keyexpr_from_string(&key_expr, "key/expression");
 
       z_owned_subscriber_t sub;
-      if (z_declare_subscriber(&sub, z_loan(s), z_loan(key_expr) z_move(callback), NULL) != 0) {
+      if (z_subscriber_declare(&sub, z_loan(s), z_loan(key_expr) z_move(callback), NULL) != 0) {
           printf("Unable to create Zenoh subscriber.\n");
           z_drop(z_move(s));
           exit(-1);
@@ -92,7 +92,7 @@ Subscribe
           c = fgetc(stdin);
       }
 
-      z_undeclare_subscriber(z_move(sub));
+      z_drop(z_move(sub));
       z_drop(z_move(s));
       return 0;
   }
@@ -205,7 +205,7 @@ Queryable
           c = fgetc(stdin);
       }
 
-      z_undeclare_queryable(z_move(qable));
+      z_drop(z_move(qable));
       z_drop(z_move(s));
       return 0;
   }

examples/z_ping.c

@@ -46,11 +46,11 @@ int main(int argc, char** argv) {
     z_view_keyexpr_t pong;
     z_view_keyexpr_from_str_unchecked(&pong, "test/pong");
     z_owned_publisher_t pub;
-    z_declare_publisher(&pub, z_loan(session), z_loan(ping), NULL);
+    z_publisher_declare(&pub, z_loan(session), z_loan(ping), NULL);
     z_owned_closure_sample_t respond;
     z_closure(&respond, callback, drop, (void*)(&pub));
     z_owned_subscriber_t sub;
-    z_declare_subscriber(&sub, z_loan(session), z_loan(pong), z_move(respond), NULL);
+    z_subscriber_declare(&sub, z_loan(session), z_loan(pong), z_move(respond), NULL);
     uint8_t* data = z_malloc(args.size);
     for (int i = 0; i < args.size; i++) {
         data[i] = i % 10;
@@ -90,8 +90,8 @@ int main(int argc, char** argv) {
     z_mutex_unlock(z_loan_mut(mutex));
     z_free(results);
     z_free(data);
-    z_undeclare_subscriber(z_move(sub));
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(sub));
+    z_drop(z_move(pub));
     z_drop(z_move(mutex));
     z_drop(z_move(session));
 }

examples/z_ping_shm.c

@@ -64,11 +64,11 @@ int main(int argc, char** argv) {
     z_view_keyexpr_t pong;
     z_view_keyexpr_from_str_unchecked(&pong, "test/pong");
     z_owned_publisher_t pub;
-    z_declare_publisher(&pub, z_loan(session), z_loan(ping), NULL);
+    z_publisher_declare(&pub, z_loan(session), z_loan(ping), NULL);
     z_owned_closure_sample_t respond;
     z_closure(&respond, callback, drop, (void*)(&pub));
     z_owned_subscriber_t sub;
-    z_declare_subscriber(&sub, z_loan(session), z_loan(pong), z_move(respond), NULL);
+    z_subscriber_declare(&sub, z_loan(session), z_loan(pong), z_move(respond), NULL);
 
     // Create SHM Provider
     z_alloc_alignment_t alignment = {0};
@@ -133,8 +133,8 @@ int main(int argc, char** argv) {
     }
     z_mutex_unlock(z_loan_mut(mutex));
     z_free(results);
-    z_undeclare_subscriber(z_move(sub));
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(sub));
+    z_drop(z_move(pub));
     z_drop(z_move(mutex));
     z_drop(z_move(session));
 

examples/z_pong.c

@@ -14,7 +14,7 @@ void callback(z_loaned_sample_t* sample, void* context) {
 }
 void drop(void* context) {
     z_owned_publisher_t* pub = (z_owned_publisher_t*)context;
-    z_undeclare_publisher(z_move(*pub));
+    z_drop(z_move(*pub));
     // A note on lifetimes:
     //  here, `sub` takes ownership of `pub` and will drop it before returning from its own `drop`,
     //  which makes passing a pointer to the stack safe as long as `sub` is dropped in a scope where `pub` is still
@@ -34,16 +34,15 @@ int main(int argc, char** argv) {
     z_view_keyexpr_t pong;
     z_view_keyexpr_from_str_unchecked(&pong, "test/pong");
     z_owned_publisher_t pub;
-    z_declare_publisher(&pub, z_loan(session), z_loan(pong), NULL);
+    z_publisher_declare(&pub, z_loan(session), z_loan(pong), NULL);
     z_owned_closure_sample_t respond;
     z_closure(&respond, callback, drop, (void*)&pub);
-    z_owned_subscriber_t sub;
-    z_declare_subscriber(&sub, z_loan(session), z_loan(ping), z_move(respond), NULL);
+    z_subscriber_declare_background(z_loan(session), z_loan(ping), z_move(respond), NULL);
 
     while (1) {
         z_sleep_s(1);
     }
-    z_undeclare_subscriber(z_move(sub));
+
     z_drop(z_move(session));
 }
 

examples/z_pub.c

@@ -54,7 +54,7 @@ int main(int argc, char** argv) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, args.keyexpr);
-    if (z_declare_publisher(&pub, z_loan(s), z_loan(ke), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_loan(s), z_loan(ke), NULL) < 0) {
         printf("Unable to declare Publisher for key expression!\n");
         exit(-1);
     }
@@ -89,11 +89,11 @@ int main(int argc, char** argv) {
     }
 #if defined(Z_FEATURE_UNSTABLE_API)
     if (args.add_matching_listener) {
-        zc_publisher_matching_listener_undeclare(z_move(listener));
+        z_drop(z_move(listener));
     }
 #endif
 
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
     z_drop(z_move(s));
     return 0;
 }

examples/z_pub_attachment.c

@@ -48,7 +48,7 @@ int main(int argc, char** argv) {
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, args.keyexpr);
     z_owned_publisher_t pub;
-    if (z_declare_publisher(&pub, z_loan(s), z_loan(ke), NULL)) {
+    if (z_publisher_declare(&pub, z_loan(s), z_loan(ke), NULL)) {
         printf("Unable to declare Publisher for key expression!\n");
         exit(-1);
     }
@@ -88,7 +88,7 @@ int main(int argc, char** argv) {
         z_publisher_put(z_loan(pub), z_move(payload), &options);
     }
 
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
 
     z_drop(z_move(s));
 

examples/z_pub_cache.c

@@ -56,7 +56,7 @@ int main(int argc, char** argv) {
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, args.keyexpr);
 
-    if (ze_declare_publication_cache(&pub_cache, z_loan(s), z_loan(ke), &pub_cache_opts) != Z_OK) {
+    if (ze_publication_cache_declare(&pub_cache, z_loan(s), z_loan(ke), &pub_cache_opts) != Z_OK) {
         printf("Unable to declare publication cache for key expression!\n");
         exit(-1);
     }
@@ -73,7 +73,7 @@ int main(int argc, char** argv) {
         z_put(z_loan(s), z_loan(ke), z_move(payload), NULL);
     }
 
-    ze_undeclare_publication_cache(z_move(pub_cache));
+    z_drop(z_move(pub_cache));
     z_drop(z_move(s));
 
     return 0;

examples/z_pub_shm.c

@@ -55,7 +55,7 @@ int main(int argc, char** argv) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, args.keyexpr);
-    if (z_declare_publisher(&pub, z_loan(s), z_loan(ke), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_loan(s), z_loan(ke), NULL) < 0) {
         printf("Unable to declare Publisher for key expression!\n");
         exit(-1);
     }
@@ -111,11 +111,11 @@ int main(int argc, char** argv) {
 
 #if defined(Z_FEATURE_UNSTABLE_API)
     if (args.add_matching_listener) {
-        zc_publisher_matching_listener_undeclare(z_move(listener));
+        z_drop(z_move(listener));
     }
 #endif
 
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
     z_drop(z_move(s));
 
     z_drop(z_move(provider));

examples/z_pub_shm_thr.c

@@ -53,7 +53,7 @@ int main(int argc, char **argv) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, keyexpr);
-    if (z_declare_publisher(&pub, z_loan(s), z_loan(ke), &options)) {
+    if (z_publisher_declare(&pub, z_loan(s), z_loan(ke), &options)) {
         printf("Unable to declare publisher for key expression!\n");
         exit(-1);
     }
@@ -88,7 +88,7 @@ int main(int argc, char **argv) {
         z_publisher_put(z_loan(pub), z_move(payload), NULL);
     }
 
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
     z_drop(z_move(s));
 
     z_drop(z_move(shm));

examples/z_pub_thr.c

@@ -48,7 +48,7 @@ int main(int argc, char** argv) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, keyexpr);
-    if (z_declare_publisher(&pub, z_loan(s), z_loan(ke), &options)) {
+    if (z_publisher_declare(&pub, z_loan(s), z_loan(ke), &options)) {
         printf("Unable to declare publisher for key expression!\n");
         exit(-1);
     }
@@ -62,7 +62,7 @@ int main(int argc, char** argv) {
         z_publisher_put(z_loan(pub), z_move(to_send), NULL);
     }
 
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
     z_drop(z_move(s));
 }
 

examples/z_pull.c

@@ -59,7 +59,7 @@ int main(int argc, char** argv) {
     z_view_keyexpr_from_str(&ke, args.keyexpr);
     z_owned_subscriber_t sub;
 
-    if (z_declare_subscriber(&sub, z_loan(s), z_loan(ke), z_move(closure), NULL) < 0) {
+    if (z_subscriber_declare(&sub, z_loan(s), z_loan(ke), z_move(closure), NULL) < 0) {
         printf("Unable to declare subscriber.\n");
         exit(-1);
     }
@@ -80,7 +80,7 @@ int main(int argc, char** argv) {
             }
         }
     }
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
     z_drop(z_move(s));
     return 0;
 }

examples/z_query_sub.c

@@ -59,7 +59,7 @@ int main(int argc, char** argv) {
     z_closure(&callback, data_handler, NULL, NULL);
     printf("Declaring querying subscriber on '%s'...\n", args.keyexpr);
     ze_owned_querying_subscriber_t sub;
-    if (ze_declare_querying_subscriber(&sub, z_loan(s), z_loan(ke), z_move(callback), &sub_opts) < 0) {
+    if (ze_querying_subscriber_declare(&sub, z_loan(s), z_loan(ke), z_move(callback), &sub_opts) < 0) {
         printf("Unable to declare querying subscriber.\n");
         exit(-1);
     }
@@ -69,7 +69,7 @@ int main(int argc, char** argv) {
         z_sleep_s(1);
     }
 
-    ze_undeclare_querying_subscriber(z_move(sub));
+    z_drop(z_move(sub));
     z_drop(z_move(s));
 
     return 0;

examples/z_queryable.c

@@ -96,7 +96,7 @@ int main(int argc, char **argv) {
         z_sleep_s(1);
     }
 
-    z_undeclare_queryable(z_move(qable));
+    z_drop(z_move(qable));
     z_drop(z_move(s));
     return 0;
 }

examples/z_queryable_shm.c

@@ -133,7 +133,7 @@ int main(int argc, char **argv) {
         }
     }
 
-    z_undeclare_queryable(z_move(qable));
+    z_drop(z_move(qable));
     z_drop(z_move(s));
     z_drop(z_move(layout));
     z_drop(z_move(provider));

examples/z_queryable_with_channels.c

@@ -90,7 +90,7 @@ int main(int argc, char** argv) {
         z_drop(z_move(oquery));
     }
 
-    z_undeclare_queryable(z_move(qable));
+    z_drop(z_move(qable));
     z_drop(z_move(handler));
     z_drop(z_move(s));
     return 0;

examples/z_sub.c

@@ -70,7 +70,7 @@ int main(int argc, char **argv) {
     z_closure(&callback, data_handler, NULL, NULL);
     printf("Declaring Subscriber on '%s'...\n", args.keyexpr);
     z_owned_subscriber_t sub;
-    if (z_declare_subscriber(&sub, z_loan(s), z_loan(ke), z_move(callback), NULL) < 0) {
+    if (z_subscriber_declare(&sub, z_loan(s), z_loan(ke), z_move(callback), NULL) < 0) {
         printf("Unable to declare subscriber.\n");
         exit(-1);
     }
@@ -80,7 +80,7 @@ int main(int argc, char **argv) {
         z_sleep_s(1);
     }
 
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
     z_drop(z_move(s));
     return 0;
 }

examples/z_sub_attachment.c

@@ -74,7 +74,7 @@ int main(int argc, char** argv) {
     z_closure(&callback, data_handler, NULL, NULL);
     printf("Declaring Subscriber on '%s'...\n", args.keyexpr);
     z_owned_subscriber_t sub;
-    if (z_declare_subscriber(&sub, z_loan(s), z_loan(ke), z_move(callback), NULL)) {
+    if (z_subscriber_declare(&sub, z_loan(s), z_loan(ke), z_move(callback), NULL)) {
         printf("Unable to declare subscriber.\n");
         exit(-1);
     }
@@ -84,7 +84,7 @@ int main(int argc, char** argv) {
         z_sleep_s(1);
     }
 
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
     z_drop(z_move(s));
     return 0;
 }