From fbc6babbd7032d30c420729ff613136e39412eb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Mon, 22 Feb 2021 16:23:30 +0100 Subject: [PATCH] CDRIVER-3904 improve documentation regarding when to call mongoc_log_set_handler (#739) --- src/libmongoc/doc/includes/init_cleanup.txt | 2 ++ src/libmongoc/doc/logging.rst | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/src/libmongoc/doc/includes/init_cleanup.txt b/src/libmongoc/doc/includes/init_cleanup.txt index 62fc594820..a53d43bdca 100644 --- a/src/libmongoc/doc/includes/init_cleanup.txt +++ b/src/libmongoc/doc/includes/init_cleanup.txt @@ -1,3 +1,5 @@ Initialize the MongoDB C Driver by calling :symbol:`mongoc_init` exactly once at the beginning of your program. It is responsible for initializing global state such as process counters, SSL, and threading primitives. +Exception to this is ``mongoc_log_set_handler()``, which should be called before ``mongoc_init()`` or some log traces would not use your log handling function. See :ref:`Custom Log Handlers ` for a detailed example. + Call :symbol:`mongoc_cleanup` exactly once at the end of your program to release all memory and other resources allocated by the driver. You must not call any other MongoDB C Driver functions after :symbol:`mongoc_cleanup`. Note that :symbol:`mongoc_init` does **not** reinitialize the driver after :symbol:`mongoc_cleanup`. diff --git a/src/libmongoc/doc/logging.rst b/src/libmongoc/doc/logging.rst index ebc01b3581..39876463d4 100644 --- a/src/libmongoc/doc/logging.rst +++ b/src/libmongoc/doc/logging.rst @@ -65,6 +65,8 @@ To make logging a little less painful, various helper macros are provided. See t MONGOC_WARNING ("An error occurred: %s", strerror (errno)); +.. _custom_log_handlers: + Custom Log Handlers ------------------- @@ -100,6 +102,9 @@ For example, you could register a custom handler to suppress messages at INFO le return 0; } +Note that in the example above ``mongoc_log_set_handler()`` is called before ``mongoc_init()``. +Otherwise, some log traces could not be processed by the log handler. + To restore the default handler: .. code-block:: c