This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new 5839a96c Document the single-threaded configuration constraint (#743)
5839a96c is described below
commit 5839a96c703f373f5e98b205246f04ef22205b48
Author: Stephen Webb <[email protected]>
AuthorDate: Fri Aug 28 11:58:38 2026 +1000
Document the single-threaded configuration constraint (#743)
---
src/main/include/log4cxx/spi/configurator.h | 5 +++++
src/site/markdown/threading.md | 13 +++++++++----
2 files changed, 14 insertions(+), 4 deletions(-)
diff --git a/src/main/include/log4cxx/spi/configurator.h
b/src/main/include/log4cxx/spi/configurator.h
index de19844a..3192df4a 100644
--- a/src/main/include/log4cxx/spi/configurator.h
+++ b/src/main/include/log4cxx/spi/configurator.h
@@ -51,6 +51,8 @@ class LOG4CXX_EXPORT Configurator : virtual public
helpers::Object
If \c repository is not provided,
the spi::LoggerRepository held by LogManager is used.
+ @warning Concurrent calls from multiple thread is *undefined
behavior*.
+
@param configFileName The file to parse
@param repository Holds the Logger instances.
*/
@@ -78,6 +80,9 @@ class LOG4CXX_EXPORT Configurator : virtual public
helpers::Object
- PROGRAM_FILE_PATH.FILENAME
- PROGRAM_FILE_PATH.STEM
- PROGRAM_FILE_PATH.EXTENSION
+
+ @warning This method is not thread-safe.
+ @return a mutable map - modification and use must be confined
to a single thread.
*/
static helpers::Properties& properties();
diff --git a/src/site/markdown/threading.md b/src/site/markdown/threading.md
index c98b880d..8d19a2a7 100644
--- a/src/site/markdown/threading.md
+++ b/src/site/markdown/threading.md
@@ -22,9 +22,14 @@ Threading {#threading}
-->
[TOC]
-Log4cxx is designed to be thread-safe under under normal usage. This
-means that logging itself is always thread-safe, however there are
-certain circumstances that can cause threading issues with Log4cxx.
+Log4cxx is designed to be thread-safe under under normal usage.
+This means that multiple threads can concurrently send logging events to an
appender.
+
+Log4cxx *requires* that configuration occurs in a single-threaded context
+(typically during application startup before worker threads are spawned
+or in a single watch-dog thread).
+
+However there are certain circumstances that can cause threading issues with
Log4cxx.
## Unexpected Exit {#unexpected-exit}
@@ -85,7 +90,7 @@ In the event that you need special signal handling, you can
implement your own
functions, and use the [ThreadUtility::configureFuncs](@ref
log4cxx.helpers.ThreadUtility.configureFuncs) method in order to
customize exactly what happens.
-### Configuring Thread {#configuring}
+### Runtime Configuration{#configuring}
To tell Log4cxx what to do by default when starting a new thread, the enum
[ThreadConfigurationType](@ref log4cxx.helpers.ThreadConfigurationType) may be
