Logging (#580)

* renamed zc_init_logger -> zc_init_logging;
added support for providing custom callbacks for logging messages;

* format

* clippy

* add missing dependency

Cargo.toml

@@ -54,6 +54,7 @@ unwrap-infallible = "0.1.5"
 const_format = "0.2.32"
 zenoh = { version = "0.11.0-dev", git = "https://github.com/eclipse-zenoh/zenoh.git", branch = "dev/1.0.0", default-features = false, features = ["internal"] }
 zenoh-ext = { version = "0.11.0-dev", git = "https://github.com/eclipse-zenoh/zenoh.git", branch = "dev/1.0.0" , optional = true }
+zenoh-util = { version = "0.11.0-dev", git = "https://github.com/eclipse-zenoh/zenoh.git", branch = "dev/1.0.0"  }
 flume = "*"
 
 [build-dependencies]

Cargo.toml.in

@@ -54,6 +54,7 @@ unwrap-infallible = "0.1.5"
 const_format = "0.2.32"
 zenoh = { version = "0.11.0-dev", git = "https://github.com/eclipse-zenoh/zenoh.git", branch = "dev/1.0.0", default-features = false, features = ["internal"] }
 zenoh-ext = { version = "0.11.0-dev", git = "https://github.com/eclipse-zenoh/zenoh.git", branch = "dev/1.0.0" , optional = true }
+zenoh-util = { version = "0.11.0-dev", git = "https://github.com/eclipse-zenoh/zenoh.git", branch = "dev/1.0.0"  }
 flume = "*"
 
 [build-dependencies]

README.md

@@ -213,7 +213,7 @@ Finally, we strongly advise that you refrain from using structure field that sta
 
 ## Logging
 
-By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logger` function.
+By default, zenoh-c enables Zenoh's logging library upon using the `z_open` or `z_scout` functions. This behavior can be disabled by adding `-DDISABLE_LOGGER_AUTOINIT:bool=true` to the `cmake` configuration command. The logger may then be manually re-enabled with the `zc_init_logging` function.
 
 ## Cross-Compilation
 

build-resources/opaque-types/src/lib.rs

@@ -63,7 +63,6 @@ pub struct CSlice {
     _context: *mut c_void,
 }
 
-
 get_opaque_type_data!(CSlice, z_owned_slice_t);
 /// A contiguous sequence of bytes owned by some other entity.
 get_opaque_type_data!(CSlice, z_view_slice_t);

docs/api.rst

@@ -877,3 +877,19 @@ Functions
 
 .. doxygenfunction:: ze_querying_subscriber_options_default
 .. doxygenfunction:: zc_reply_keyexpr_default
+
+Logging
+=======
+
+Types
+-----
+
+.. doxygenstruct:: zc_owned_closure_log_t
+.. doxygenstruct:: zc_loaned_closure_log_t
+.. doxygenenum:: zc_log_severity_t
+
+Functions
+---------
+
+.. doxygenfunction:: zc_init_logging
+.. doxygenfunction:: zc_init_logging_with_callback

include/zenoh_commons.h

@@ -218,6 +218,41 @@ typedef enum zc_locality_t {
   ZC_LOCALITY_REMOTE = 2,
 } zc_locality_t;
 #endif
+/**
+ * Severity level of Zenoh log message.
+ */
+typedef enum zc_log_severity_t {
+  /**
+   * The `trace` level.
+   *
+   * Designates very low priority, often extremely verbose, information.
+   */
+  ZC_LOG_SEVERITY_TRACE = 0,
+  /**
+   * The "debug" level.
+   *
+   * Designates lower priority information.
+   */
+  ZC_LOG_SEVERITY_DEBUG = 1,
+  /**
+   * The "info" level.
+   *
+   * Designates useful information.
+   */
+  ZC_LOG_SEVERITY_INFO = 2,
+  /**
+   * The "warn" level.
+   *
+   * Designates hazardous situations.
+   */
+  ZC_LOG_SEVERITY_WARN = 3,
+  /**
+   * The "error" level.
+   *
+   * Designates very serious errors.
+   */
+  ZC_LOG_SEVERITY_ERROR = 4,
+} zc_log_severity_t;
 /**
  * Key expressions types to which Queryable should reply to.
  */
@@ -337,6 +372,30 @@ typedef struct z_owned_closure_hello_t {
    */
   void (*drop)(void *context);
 } z_owned_closure_hello_t;
+/**
+ * A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks:
+ *
+ * Closures are not guaranteed not to be called concurrently.
+ *
+ * It is guaranteed that:
+ *   - `call` will never be called once `drop` has started.
+ *   - `drop` will only be called **once**, and **after every** `call` has ended.
+ *   - The two previous guarantees imply that `call` and `drop` are never called concurrently.
+ */
+typedef struct zc_owned_closure_log_t {
+  /**
+   * An optional pointer to a closure state.
+   */
+  void *context;
+  /**
+   * A closure body.
+   */
+  void (*call)(enum zc_log_severity_t severity, const struct z_loaned_string_t *msg, void *context);
+  /**
+   * An optional drop function that will be called when the closure is dropped.
+   */
+  void (*drop)(void *context);
+} zc_owned_closure_log_t;
 /**
  * A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks:
  *
@@ -1549,6 +1608,30 @@ ZENOHC_API void z_closure_hello_null(struct z_owned_closure_hello_t *this_);
  * Calls the closure. Calling an uninitialized closure is a no-op.
  */
 ZENOHC_API
+void z_closure_log_call(const struct zc_loaned_closure_log_t *closure,
+                        enum zc_log_severity_t severity,
+                        const struct z_loaned_string_t *msg);
+/**
+ * Returns ``true`` if closure is valid, ``false`` if it is in gravestone state.
+ */
+ZENOHC_API bool z_closure_log_check(const struct zc_owned_closure_log_t *this_);
+/**
+ * Drops the closure. Droping an uninitialized closure is a no-op.
+ */
+ZENOHC_API void z_closure_log_drop(struct zc_owned_closure_log_t *closure);
+/**
+ * Borrows closure.
+ */
+ZENOHC_API
+const struct zc_loaned_closure_log_t *z_closure_log_loan(const struct zc_owned_closure_log_t *closure);
+/**
+ * Constructs a closure in a gravestone state.
+ */
+ZENOHC_API void z_closure_log_null(struct zc_owned_closure_log_t *this_);
+/**
+ * Calls the closure. Calling an uninitialized closure is a no-op.
+ */
+ZENOHC_API
 void z_closure_query_call(const struct z_loaned_closure_query_t *closure,
                           const struct z_loaned_query_t *query);
 /**
@@ -4304,12 +4387,22 @@ ZENOHC_API
 z_result_t zc_config_to_string(const struct z_loaned_config_t *config,
                                struct z_owned_string_t *out_config_string);
 /**
- * Initialises the zenoh runtime logger.
+ * Initializes the zenoh runtime logger, using rust environment settings.
  *
  * Note that unless you built zenoh-c with the `logger-autoinit` feature disabled,
  * this will be performed automatically by `z_open` and `z_scout`.
  */
-ZENOHC_API void zc_init_logger(void);
+ZENOHC_API void zc_init_logging(void);
+/**
+ * Initializes the zenoh runtime logger with custom callback.
+ *
+ * @param min_severity: Minimum severity level of log message to be be passed to the `callback`.
+ * Messages with lower severity levels will be ignored.
+ * @param callback: A closure that will be called with each log message severity level and content.
+ */
+ZENOHC_API
+void zc_init_logging_with_callback(enum zc_log_severity_t min_severity,
+                                   struct zc_owned_closure_log_t *callback);
 /**
  * Constructs default value for `zc_liveliness_declaration_options_t`.
  */

include/zenoh_macros.h

@@ -9,6 +9,7 @@
         z_owned_bytes_t : z_bytes_loan, \
         z_owned_bytes_writer_t : z_bytes_writer_loan, \
         z_owned_closure_hello_t : z_closure_hello_loan, \
+        zc_owned_closure_log_t : z_closure_log_loan, \
         z_owned_closure_query_t : z_closure_query_loan, \
         z_owned_closure_reply_t : z_closure_reply_loan, \
         z_owned_closure_sample_t : z_closure_sample_loan, \
@@ -56,6 +57,7 @@
         z_owned_bytes_t* : z_bytes_drop, \
         z_owned_bytes_writer_t* : z_bytes_writer_drop, \
         z_owned_closure_hello_t* : z_closure_hello_drop, \
+        zc_owned_closure_log_t* : z_closure_log_drop, \
         z_owned_closure_query_t* : z_closure_query_drop, \
         z_owned_closure_reply_t* : z_closure_reply_drop, \
         z_owned_closure_sample_t* : z_closure_sample_drop, \
@@ -91,6 +93,7 @@
         z_owned_bytes_t* : z_bytes_null, \
         z_owned_bytes_writer_t* : z_bytes_writer_null, \
         z_owned_closure_hello_t* : z_closure_hello_null, \
+        zc_owned_closure_log_t* : z_closure_log_null, \
         z_owned_closure_query_t* : z_closure_query_null, \
         z_owned_closure_reply_t* : z_closure_reply_null, \
         z_owned_closure_sample_t* : z_closure_sample_null, \
@@ -128,6 +131,7 @@
         z_owned_bytes_t : z_bytes_check, \
         z_owned_bytes_writer_t : z_bytes_writer_check, \
         z_owned_closure_hello_t : z_closure_hello_check, \
+        zc_owned_closure_log_t : z_closure_log_check, \
         z_owned_closure_query_t : z_closure_query_check, \
         z_owned_closure_reply_t : z_closure_reply_check, \
         z_owned_closure_sample_t : z_closure_sample_check, \
@@ -197,6 +201,7 @@
 inline const z_loaned_bytes_t* z_loan(const z_owned_bytes_t& this_) { return z_bytes_loan(&this_); };
 inline const z_loaned_bytes_writer_t* z_loan(const z_owned_bytes_writer_t& this_) { return z_bytes_writer_loan(&this_); };
 inline const z_loaned_closure_hello_t* z_loan(const z_owned_closure_hello_t& closure) { return z_closure_hello_loan(&closure); };
+inline const zc_loaned_closure_log_t* z_loan(const zc_owned_closure_log_t& closure) { return z_closure_log_loan(&closure); };
 inline const z_loaned_closure_query_t* z_loan(const z_owned_closure_query_t& closure) { return z_closure_query_loan(&closure); };
 inline const z_loaned_closure_reply_t* z_loan(const z_owned_closure_reply_t& closure) { return z_closure_reply_loan(&closure); };
 inline const z_loaned_closure_sample_t* z_loan(const z_owned_closure_sample_t& closure) { return z_closure_sample_loan(&closure); };
@@ -240,6 +245,7 @@ inline z_loaned_string_array_t* z_loan_mut(z_owned_string_array_t& this_) { retu
 inline void z_drop(z_owned_bytes_t* this_) { return z_bytes_drop(this_); };
 inline void z_drop(z_owned_bytes_writer_t* this_) { return z_bytes_writer_drop(this_); };
 inline void z_drop(z_owned_closure_hello_t* closure) { return z_closure_hello_drop(closure); };
+inline void z_drop(zc_owned_closure_log_t* closure) { return z_closure_log_drop(closure); };
 inline void z_drop(z_owned_closure_query_t* closure) { return z_closure_query_drop(closure); };
 inline void z_drop(z_owned_closure_reply_t* closure) { return z_closure_reply_drop(closure); };
 inline void z_drop(z_owned_closure_sample_t* closure) { return z_closure_sample_drop(closure); };
@@ -271,6 +277,7 @@ inline void z_drop(z_owned_subscriber_t* this_) { return z_subscriber_drop(this_
 inline z_owned_bytes_t* z_move(z_owned_bytes_t& this_) { return (&this_); };
 inline z_owned_bytes_writer_t* z_move(z_owned_bytes_writer_t& this_) { return (&this_); };
 inline z_owned_closure_hello_t* z_move(z_owned_closure_hello_t& closure) { return (&closure); };
+inline zc_owned_closure_log_t* z_move(zc_owned_closure_log_t& closure) { return (&closure); };
 inline z_owned_closure_query_t* z_move(z_owned_closure_query_t& closure) { return (&closure); };
 inline z_owned_closure_reply_t* z_move(z_owned_closure_reply_t& closure) { return (&closure); };
 inline z_owned_closure_sample_t* z_move(z_owned_closure_sample_t& closure) { return (&closure); };
@@ -302,6 +309,7 @@ inline z_owned_subscriber_t* z_move(z_owned_subscriber_t& this_) { return (&this
 inline void z_null(z_owned_bytes_t* this_) { return z_bytes_null(this_); };
 inline void z_null(z_owned_bytes_writer_t* this_) { return z_bytes_writer_null(this_); };
 inline void z_null(z_owned_closure_hello_t* this_) { return z_closure_hello_null(this_); };
+inline void z_null(zc_owned_closure_log_t* this_) { return z_closure_log_null(this_); };
 inline void z_null(z_owned_closure_query_t* this_) { return z_closure_query_null(this_); };
 inline void z_null(z_owned_closure_reply_t* this_) { return z_closure_reply_null(this_); };
 inline void z_null(z_owned_closure_sample_t* this_) { return z_closure_sample_null(this_); };
@@ -337,6 +345,7 @@ inline void z_null(z_view_string_t* this_) { return z_view_string_null(this_); }
 inline bool z_check(const z_owned_bytes_t& this_) { return z_bytes_check(&this_); };
 inline bool z_check(const z_owned_bytes_writer_t& this_) { return z_bytes_writer_check(&this_); };
 inline bool z_check(const z_owned_closure_hello_t& this_) { return z_closure_hello_check(&this_); };
+inline bool z_check(const zc_owned_closure_log_t& this_) { return z_closure_log_check(&this_); };
 inline bool z_check(const z_owned_closure_query_t& this_) { return z_closure_query_check(&this_); };
 inline bool z_check(const z_owned_closure_reply_t& this_) { return z_closure_reply_check(&this_); };
 inline bool z_check(const z_owned_closure_sample_t& this_) { return z_closure_sample_check(&this_); };
@@ -468,6 +477,8 @@ template<> struct z_loaned_to_owned_type_t<z_loaned_bytes_writer_t> { typedef z_
 template<> struct z_owned_to_loaned_type_t<z_owned_bytes_writer_t> { typedef z_loaned_bytes_writer_t type; };
 template<> struct z_loaned_to_owned_type_t<z_loaned_closure_hello_t> { typedef z_owned_closure_hello_t type; };
 template<> struct z_owned_to_loaned_type_t<z_owned_closure_hello_t> { typedef z_loaned_closure_hello_t type; };
+template<> struct z_loaned_to_owned_type_t<zc_loaned_closure_log_t> { typedef zc_owned_closure_log_t type; };
+template<> struct z_owned_to_loaned_type_t<zc_owned_closure_log_t> { typedef zc_loaned_closure_log_t type; };
 template<> struct z_loaned_to_owned_type_t<z_loaned_closure_query_t> { typedef z_owned_closure_query_t type; };
 template<> struct z_owned_to_loaned_type_t<z_owned_closure_query_t> { typedef z_loaned_closure_query_t type; };
 template<> struct z_loaned_to_owned_type_t<z_loaned_closure_reply_t> { typedef z_owned_closure_reply_t type; };

splitguide.yaml

@@ -67,6 +67,7 @@ zenoh_opaque.h:
   - z_loaned_closure_reply_t!
   - z_loaned_closure_sample_t!
   - z_loaned_closure_zid_t!
+  - zc_loaned_closure_log_t!
   - zc_loaned_closure_matching_status_t!#unstable
   - z_owned_shm_client_t!#shared-memory#unstable
   - zc_owned_shm_client_list_t!#shared-memory#unstable