This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch async_appender_documentation
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit e8ed4032f262a059cdbe782079385daa0942b331
Author: Stephen Webb <swebb2...@gmail.com>
AuthorDate: Wed May 21 12:54:23 2025 +1000
Improve the clarity of AsyncAppender documentation
---
src/main/include/log4cxx/asyncappender.h | 33 ++++++++++++++++++++++----------
src/site/markdown/concepts.md | 15 +++++++++------
2 files changed, 32 insertions(+), 16 deletions(-)
diff --git a/src/main/include/log4cxx/asyncappender.h
b/src/main/include/log4cxx/asyncappender.h
index e1ea6c8e..3b2ce467 100644
--- a/src/main/include/log4cxx/asyncappender.h
+++ b/src/main/include/log4cxx/asyncappender.h
@@ -33,14 +33,30 @@ by processing log events asynchronously.
The AsyncAppender stores the logging event in a bounded buffer
and then returns control to the application.
A separate thread forwards events to the attached appender(s).
-You can attach multiple appenders to an AsyncAppender.
The AsyncAppender is useful when outputting to a slow event sink,
for example, a remote SMTP server or a database.
-Attaching a FileAppender to AsyncAppender is not recommended
+Attaching a FileAppender to AsyncAppender
+to reduce logging overhead is not recommended
as the inter-thread communication overhead
can exceed the time to write directly to a file.
+You can attach multiple appenders to an AsyncAppender by:
+- calling AsyncAppender::addAppender repeatedly when progammatically
configuring Log4cxx.
+- adding multiple <b>appender-ref</b> elements
+to the <b>appender class="AsyncAppender"</b> element
+when using runtime configuration.
+
+<b>Important note:</b> The <code>AsyncAppender</code> can only
+be configured at runtime using XML,
+i.e. when the application uses {@link xml::DOMConfigurator DOMConfigurator}
+to load the cofiguration file.
+
+Here is a sample configuration file:
+\include async-example.xml
+
+### Configurable properties
+
When the application produces logging events faster
than the background thread is able to process,
the bounded buffer can become full.
@@ -59,8 +75,8 @@ To determine whether the application produces logging events
faster
than the background thread is able to process, enable [Log4cxx internal
debugging](internal-debugging.html).
The AsyncAppender will output a histogram of queue length frequencies when
closed.
-<b>Important note:</b> The <code>AsyncAppender</code> can only
-be script configured using the {@link xml::DOMConfigurator DOMConfigurator}.
+See AsyncAppender::setOption for details.
+
*/
class LOG4CXX_EXPORT AsyncAppender :
public virtual spi::AppenderAttachable,
@@ -88,7 +104,8 @@ class LOG4CXX_EXPORT AsyncAppender :
virtual ~AsyncAppender();
/**
- * Add appender.
+ * Ensure \c newAppender receives any logging event
+ * added to this appender.
*
* @param newAppender appender to add, may not be null.
*/
@@ -121,10 +138,7 @@ class LOG4CXX_EXPORT AsyncAppender :
AppenderPtr getAppender(const LogString& name) const override;
/**
- * Gets whether the location of the logging request call
- * should be captured.
- *
- * @return the current value of the <b>LocationInfo</b> option.
+ * The current value of the (unused) <b>LocationInfo</b> option.
*/
bool getLocationInfo() const;
/**
@@ -206,7 +220,6 @@ class LOG4CXX_EXPORT AsyncAppender :
Supported options | Supported values | Default value
-------------- | ---------------- | ---------------
- LocationInfo | True,False | False
BufferSize | int | 128
Blocking | True,False | True
diff --git a/src/site/markdown/concepts.md b/src/site/markdown/concepts.md
index 3b4584d7..c4249e61 100644
--- a/src/site/markdown/concepts.md
+++ b/src/site/markdown/concepts.md
@@ -459,16 +459,19 @@ Log4cxx provides appenders to write to:
- [a SMTP server](@ref log4cxx.net.SMTPAppender)
- [a database](@ref log4cxx.db.ODBCAppender)
-If the same file receives log requests concurrently from multiple process,
-use [this appender](@ref log4cxx.rolling.MultiprocessRollingFileAppender).
-It is also possible to log [asynchronously](@ref log4cxx.AsyncAppender)
-to another appender.
-See \ref async-example.xml
-
The [addAppender](@ref log4cxx.Logger.addAppender)
method adds an appender to a given logger.
More than one appender can be attached to a logger.
+If the same file receives log requests concurrently from multiple process,
+use [this appender](@ref log4cxx.rolling.MultiprocessRollingFileAppender)
+to ensure a file rollover is not initiated in multiple processes.
+
+It is also possible (by using [AsyncAppender](@ref log4cxx.AsyncAppender))
+to configure Log4cxx to use a background thread
+to process [logging events](@ref log4cxx.spi::LoggingEvent) asynchronously.
+See \ref async-example.xml for a configuration file example.
+
## Additivity {#appender-additivity}
Each enabled logging request for a given logger will be forwarded to all the
appenders in
