(pulsar-client-cpp) branch main updated: Document custom logger lifetime (#593)

[xy...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

BewareMyPower pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-client-cpp.git


The following commit(s) were added to refs/heads/main by this push:
     new 05f8a6d  Document custom logger lifetime (#593)
05f8a6d is described below

commit 05f8a6d16d10b2f0f76dbd82c944f4e0707a7d0a
Author: zhanglistar <zh...@bigo.sg>
AuthorDate: Thu Jun 25 10:20:50 2026 +0800

    Document custom logger lifetime (#593)
---
 README.md                               | 13 +++++++++++++
 include/pulsar/ClientConfiguration.h    | 15 +++++++++++----
 include/pulsar/c/client_configuration.h | 16 ++++++++++++++++
 3 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0bcae7b..8aff436 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,19 @@ For the supported Pulsar features, see [Client Feature Matrix](https://pulsar.ap
 
 For how to use APIs to publish and consume messages, see [examples](https://github.com/apache/pulsar-client-cpp/tree/main/examples).
 
+## Custom logger lifetime
+
+The C++ client supports one custom logger factory per process. A logger configured
+through `ClientConfiguration::setLogger` or the C API logger functions is shared
+by all clients in the same process and is not scoped to an individual client
+instance. Set the custom logger before creating clients, and do not expect
+different clients to have independent log handlers.
+
+If an application or language binding exposes logger callbacks, the callback and
+its context must remain valid until all Pulsar clients are closed and no
+background thread can emit client logs. Avoid tying the callback lifetime to a
+single client when multiple clients can exist in the process.
+
 ## Import the library into your project
 
 ### CMake with vcpkg integration
diff --git a/include/pulsar/ClientConfiguration.h b/include/pulsar/ClientConfiguration.h
index b37b7c6..c21ee5c 100644
--- a/include/pulsar/ClientConfiguration.h
+++ b/include/pulsar/ClientConfiguration.h
@@ -187,15 +187,22 @@ class PULSAR_PUBLIC ClientConfiguration {
     int getMaxBackoffIntervalMs() const;
 
     /**
-     * Configure a custom logger backend to route of Pulsar client library
+     * Configure a custom logger backend to route Pulsar client library logs
      * to a different logger implementation.
      *
      * By default, log messages are printed on standard output.
      *
      * When passed in, the configuration takes ownership of the loggerFactory object.
-     * The logger factory can only be set once per process. Any subsequent calls to
-     * set the logger factory will have no effect, though the logger factory object
-     * will be cleaned up.
+     * The logger factory is process-wide and is not scoped to a Client instance.
+     * It can only be set once per process. Any subsequent calls to set the logger
+     * factory will have no effect, though the logger factory object will be
+     * cleaned up.
+     *
+     * Applications and language bindings that use callback-based logger factories
+     * should set the logger before creating clients and ensure callback state
+     * outlives all Pulsar clients and background threads that can emit logs.
+     * Avoid using per-client callback objects that can be destroyed while another
+     * client in the same process is still running.
      */
     ClientConfiguration& setLogger(LoggerFactory* loggerFactory);
 
diff --git a/include/pulsar/c/client_configuration.h b/include/pulsar/c/client_configuration.h
index 1be7c1f..8f53438 100644
--- a/include/pulsar/c/client_configuration.h
+++ b/include/pulsar/c/client_configuration.h
@@ -141,9 +141,25 @@ PULSAR_PUBLIC void pulsar_client_configuration_set_concurrent_lookup_request(
 PULSAR_PUBLIC int pulsar_client_configuration_get_concurrent_lookup_request(
     pulsar_client_configuration_t *conf);
 
+/**
+ * Configure a custom logger for Pulsar client library logs.
+ *
+ * The logger is process-wide and is not scoped to a pulsar_client_t instance.
+ * It can only be set once per process. Applications and language bindings
+ * should set the logger before creating clients and ensure the logger callback
+ * context outlives all Pulsar clients and background threads that can emit logs.
+ */
 PULSAR_PUBLIC void pulsar_client_configuration_set_logger(pulsar_client_configuration_t *conf,
                                                           pulsar_logger logger, void *ctx);
 
+/**
+ * Configure a custom logger for Pulsar client library logs.
+ *
+ * The logger is process-wide and is not scoped to a pulsar_client_t instance.
+ * It can only be set once per process. Applications and language bindings
+ * should set the logger before creating clients and ensure the logger callback
+ * context outlives all Pulsar clients and background threads that can emit logs.
+ */
 PULSAR_PUBLIC void pulsar_client_configuration_set_logger_t(pulsar_client_configuration_t *conf,
                                                             pulsar_logger_t logger);