Subscriber/Queryable api alignment (#720)

* make z_undeclare_publisher/subscriber/queryable take their argument by reference

* remove z_undeclare_xxx functions;
add z_declare_background_subscriber/queryable functions;

* Update include/zenoh-pico/api/primitives.h

Co-authored-by: Alexander Bushnev <sashacmc@gmail.com>

* examples update

* rename z_declare_xxx functions to z_xxx_declare

---------

Co-authored-by: Alexander Bushnev <sashacmc@gmail.com>

docs/api.rst

@@ -893,10 +893,9 @@ Functions
 .. autocfunction:: primitives.h::z_put
 .. autocfunction:: primitives.h::z_delete
 
-.. autocfunction:: primitives.h::z_declare_publisher
+.. autocfunction:: primitives.h::z_publisher_declare
 .. autocfunction:: primitives.h::z_publisher_put
 .. autocfunction:: primitives.h::z_publisher_delete
-.. autocfunction:: primitives.h::z_undeclare_publisher
 .. autocfunction:: primitives.h::z_publisher_keyexpr
 
 .. autocfunction:: primitives.h::z_put_options_default
@@ -936,8 +935,8 @@ Option Types
 Functions
 ---------
 
-.. autocfunction:: primitives.h::z_declare_subscriber
-.. autocfunction:: primitives.h::z_undeclare_subscriber
+.. autocfunction:: primitives.h::z_subscriber_declare
+.. autocfunction:: primitives.h::z_subscriber_declare_background
 
 .. autocfunction:: primitives.h::z_subscriber_options_default
 .. autocfunction:: primitives.h::z_subscriber_keyexpr
@@ -981,8 +980,8 @@ Option Types
 
 Functions
 ---------
-.. autocfunction:: primitives.h::z_declare_queryable
-.. autocfunction:: primitives.h::z_undeclare_queryable
+.. autocfunction:: primitives.h::z_queryable_declare
+.. autocfunction:: primitives.h::z_queryable_declare_background
 
 .. autocfunction:: primitives.h::z_queryable_options_default
 .. autocfunction:: primitives.h::z_query_reply_options_default

examples/arduino/z_pub.ino

@@ -84,7 +84,7 @@ void setup() {
     Serial.println("...");
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_publisher(&pub, z_session_loan(&s), z_view_keyexpr_loan(&ke), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_session_loan(&s), z_view_keyexpr_loan(&ke), NULL) < 0) {
         Serial.println("Unable to declare publisher for key expression!");
         while (1) {
             ;

examples/arduino/z_pull.ino

@@ -84,7 +84,7 @@ void setup() {
     z_ring_channel_sample_new(&closure, &handler, SIZE);
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, KEYEXPR);
-    if (z_declare_subscriber(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&closure),
+    if (z_subscriber_declare(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&closure),
                              NULL) < 0) {
         Serial.println("Unable to declare subscriber.");
         return;

examples/arduino/z_queryable.ino

@@ -112,7 +112,7 @@ void setup() {
     z_closure_query(&callback, query_handler, NULL, NULL);
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_queryable(&qable, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_query_move(&callback),
+    if (z_queryable_declare(&qable, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_query_move(&callback),
                             NULL) < 0) {
         Serial.println("Unable to declare queryable.");
         while (1) {

examples/arduino/z_sub.ino

@@ -99,7 +99,7 @@ void setup() {
     z_closure_sample(&callback, data_handler, NULL, NULL);
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_subscriber(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&callback),
+    if (z_subscriber_declare(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&callback),
                              NULL) < 0) {
         Serial.println("Unable to declare subscriber.");
         while (1) {

examples/espidf/z_pub.c

@@ -143,7 +143,7 @@ void app_main() {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, 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);
     }
@@ -163,7 +163,7 @@ void app_main() {
     }
 
     printf("Closing Zenoh Session...");
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
 
     z_drop(z_move(s));
     printf("OK!\n");

examples/espidf/z_pull.c

@@ -151,7 +151,7 @@ void app_main() {
     z_owned_subscriber_t sub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, KEYEXPR);
-    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);
     }
@@ -178,7 +178,7 @@ void app_main() {
         }
     }
 
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
     z_drop(z_move(handler));
 
     z_drop(z_move(s));

examples/espidf/z_queryable.c

@@ -173,7 +173,7 @@ void app_main() {
     z_owned_queryable_t qable;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_queryable(&qable, z_loan(s), z_loan(ke), z_move(callback), NULL) < 0) {
+    if (z_queryable_declare(&qable, z_loan(s), z_loan(ke), z_move(callback), NULL) < 0) {
         printf("Unable to declare queryable.\n");
         exit(-1);
     }
@@ -185,7 +185,7 @@ void app_main() {
     }
 
     printf("Closing Zenoh Session...");
-    z_undeclare_queryable(z_move(qable));
+    z_drop(z_move(qable));
 
     z_drop(z_move(s));
     printf("OK!\n");

examples/espidf/z_sub.c

@@ -155,7 +155,7 @@ void app_main() {
     z_owned_subscriber_t sub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    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);
     }
@@ -166,7 +166,7 @@ void app_main() {
     }
 
     printf("Closing Zenoh Session...");
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
 
     z_drop(z_move(s));
     printf("OK!\n");

examples/freertos_plus_tcp/z_pub.c

@@ -86,7 +86,7 @@ void app_main(void) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, 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");
         return;
     }
@@ -107,7 +107,7 @@ void app_main(void) {
     }
 
     // Clean-up
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
     z_drop(z_move(s));
 }
 #else

examples/freertos_plus_tcp/z_pub_st.c

@@ -51,7 +51,7 @@ void app_main(void) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, 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");
         return;
     }
@@ -78,7 +78,7 @@ void app_main(void) {
         zp_send_join(z_loan(s), NULL);
     }
 
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
 
     z_drop(z_move(s));
 }

examples/freertos_plus_tcp/z_pull.c

@@ -60,7 +60,7 @@ void app_main(void) {
     z_owned_subscriber_t sub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, KEYEXPR);
-    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");
         return;
     }
@@ -87,7 +87,7 @@ void app_main(void) {
         }
     }
 
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
     z_drop(z_move(handler));
 
     z_drop(z_move(s));

examples/freertos_plus_tcp/z_queryable.c

@@ -87,7 +87,7 @@ void app_main(void) {
     z_owned_closure_query_t callback;
     z_closure(&callback, query_handler);
     z_owned_queryable_t qable;
-    if (z_declare_queryable(&qable, z_loan(s), z_loan(ke), z_move(callback), NULL) < 0) {
+    if (z_queryable_declare(&qable, z_loan(s), z_loan(ke), z_move(callback), NULL) < 0) {
         printf("Unable to create queryable.\n");
         return;
     }
@@ -96,7 +96,7 @@ void app_main(void) {
         z_sleep_s(1);
     }
 
-    z_undeclare_queryable(z_move(qable));
+    z_drop(z_move(qable));
 
     z_drop(z_move(s));
 }

examples/freertos_plus_tcp/z_sub.c

@@ -67,7 +67,7 @@ void app_main(void) {
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, 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");
         return;
     }
@@ -76,7 +76,7 @@ void app_main(void) {
         z_sleep_s(1);
     }
 
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
 
     z_drop(z_move(s));
 }

examples/freertos_plus_tcp/z_sub_st.c

@@ -64,7 +64,7 @@ void app_main(void) {
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, 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");
         return;
     }
@@ -76,7 +76,7 @@ void app_main(void) {
         zp_send_join(z_loan(s), NULL);
     }
 
-    z_undeclare_subscriber(z_move(sub));
+    z_drop(z_move(sub));
 
     z_drop(z_move(s));
 }

examples/mbed/z_pub.cpp

@@ -63,7 +63,7 @@ int main(int argc, char **argv) {
     z_owned_publisher_t pub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_publisher(&pub, z_session_loan(&s), z_view_keyexpr_loan(&ke), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_session_loan(&s), z_view_keyexpr_loan(&ke), NULL) < 0) {
         printf("Unable to declare publisher for key expression!\n");
         exit(-1);
     }
@@ -83,7 +83,7 @@ int main(int argc, char **argv) {
     }
 
     printf("Closing Zenoh Session...");
-    z_undeclare_publisher(z_publisher_move(&pub));
+    z_publisher_drop(z_publisher_move(&pub));
 
     z_session_drop(z_session_move(&s));
     printf("OK!\n");

examples/mbed/z_pull.cpp

@@ -71,7 +71,7 @@ int main(int argc, char **argv) {
     z_owned_subscriber_t sub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str(&ke, KEYEXPR);
-    if (z_declare_subscriber(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&closure),
+    if (z_subscriber_declare(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&closure),
                              NULL) < 0) {
         printf("Unable to declare subscriber.\n");
         return -1;
@@ -101,7 +101,7 @@ int main(int argc, char **argv) {
         }
     }
 
-    z_undeclare_subscriber(z_subscriber_move(&sub));
+    z_subscriber_drop(z_subscriber_move(&sub));
     z_ring_handler_sample_drop(z_ring_handler_sample_move(&handler));
 
     z_session_drop(z_session_move(&s));

examples/mbed/z_queryable.cpp

@@ -91,7 +91,7 @@ int main(int argc, char **argv) {
     z_owned_queryable_t qable;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_queryable(&qable, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_query_move(&callback),
+    if (z_queryable_declare(&qable, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_query_move(&callback),
                             NULL) < 0) {
         printf("Unable to declare queryable.\n");
         exit(-1);
@@ -104,7 +104,7 @@ int main(int argc, char **argv) {
     }
 
     printf("Closing Zenoh Session...");
-    z_undeclare_queryable(z_queryable_move(&qable));
+    z_queryable_drop(z_queryable_move(&qable));
 
     z_session_drop(z_session_move(&s));
     printf("OK!\n");

examples/mbed/z_sub.cpp

@@ -75,7 +75,7 @@ int main(int argc, char **argv) {
     z_owned_subscriber_t sub;
     z_view_keyexpr_t ke;
     z_view_keyexpr_from_str_unchecked(&ke, KEYEXPR);
-    if (z_declare_subscriber(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&callback),
+    if (z_subscriber_declare(&sub, z_session_loan(&s), z_view_keyexpr_loan(&ke), z_closure_sample_move(&callback),
                              NULL) < 0) {
         printf("Unable to declare subscriber.\n");
         exit(-1);
@@ -87,7 +87,7 @@ int main(int argc, char **argv) {
     }
 
     printf("Closing Zenoh Session...");
-    z_undeclare_subscriber(z_subscriber_move(&sub));
+    z_subscriber_drop(z_subscriber_move(&sub));
 
     z_session_drop(z_session_move(&s));
     printf("OK!\n");

examples/unix/c11/z_ping.c

@@ -83,15 +83,15 @@ int main(int argc, char** argv) {
     z_view_keyexpr_from_str_unchecked(&pong, "test/pong");
 
     z_owned_publisher_t pub;
-    if (z_declare_publisher(&pub, z_loan(session), z_loan(ping), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_loan(session), z_loan(ping), NULL) < 0) {
         printf("Unable to declare publisher for key expression!\n");
         return -1;
     }
 
     z_owned_closure_sample_t respond;
     z_closure(&respond, callback, drop, NULL);
     z_owned_subscriber_t sub;
-    if (z_declare_subscriber(&sub, z_loan(session), z_loan(pong), z_move(respond), NULL) < 0) {
+    if (z_subscriber_declare(&sub, z_loan(session), z_loan(pong), z_move(respond), NULL) < 0) {
         printf("Unable to declare subscriber for key expression.\n");
         return -1;
     }

examples/unix/c11/z_pong.c

@@ -51,7 +51,7 @@ 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;
-    if (z_declare_publisher(&pub, z_loan(session), z_loan(pong), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_loan(session), z_loan(pong), NULL) < 0) {
         printf("Unable to declare publisher for key expression!\n");
         return -1;
     }
@@ -60,17 +60,14 @@ int main(int argc, char** argv) {
     z_view_keyexpr_from_str_unchecked(&ping, "test/ping");
     z_owned_closure_sample_t respond;
     z_closure(&respond, callback, drop, (void*)(&pub));
-    z_owned_subscriber_t sub;
-    if (z_declare_subscriber(&sub, z_loan(session), z_loan(ping), z_move(respond), NULL) < 0) {
+    if (z_subscriber_declare_background(z_loan(session), z_loan(ping), z_move(respond), NULL) < 0) {
         printf("Unable to declare subscriber for key expression.\n");
         return -1;
     }
 
     while (getchar() != 'q') {
     }
 
-    z_drop(z_move(sub));
-
     z_drop(z_move(session));
 }
 #else

examples/unix/c11/z_pub.c

@@ -99,7 +99,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), NULL) < 0) {
+    if (z_publisher_declare(&pub, z_loan(s), z_loan(ke), NULL) < 0) {
         printf("Unable to declare publisher for key expression!\n");
         return -1;
     }
@@ -119,7 +119,7 @@ int main(int argc, char **argv) {
         z_publisher_put(z_loan(pub), z_move(payload), NULL);
     }
     // Clean up
-    z_undeclare_publisher(z_move(pub));
+    z_drop(z_move(pub));
     z_drop(z_move(s));
     return 0;
 }