This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch doc/perf-main
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 49d154e591e2379787fdbb401c225fb8f67656ed
Author: Volkan Yazıcı <vol...@yazi.ci>
AuthorDate: Thu May 16 09:41:29 2024 +0200
Document recyclers
---
.../modules/ROOT/pages/manual/garbagefree.adoc | 91 ++++++++++++++++++++++
.../partials/properties-garbage-collection.adoc | 30 +++++++
2 files changed, 121 insertions(+)
diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
index 79c1d26430..88b2d6cc06 100644
--- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
@@ -135,6 +135,97 @@ objects for thread safety)
Any other filter not shared in the above list is not garbage-free.
+[#recyclers]
+=== Recyclers
+
+Log4j contains the _recycler_ abstraction that models the buffer-and-reuse
strategy used to operate without any extra memory allocations at steady state.
+Recyclers implement the `RecyclerFactoryProvider` interface in `log4j-kit` (a
dependency of `log4j-core`) and provide themselves as a `ServiceLoader`.
+Hence, you can easily implement custom recyclers and inject them using the
`ServiceLoader` mechanism.
+
+Log4j chooses a recycler using the following procedure:
+
+. Using `ServiceLoader` mechanism, loads all available
`RecyclerFactoryProvider` implementations
+. Sorts providers (the lower `order` value will come first)
+. If xref:#log4j.recycler.factory[] is provided, the first provider whose name
matching with this property value will be used. Otherwise, the first provider
will be used.
+
+The predefined recycler factory providers are as follows:
+
+[#recyclers-dummy]
+==== Dummy recycler
+
+[cols="1h,5"]
+|===
+| Module
+| `log4j-kit`
+
+| Name
+| `dummy`
+
+| Order
+| 900
+|===
+
+Does not recycle anything; all instances are freshly created.
+(Not recommended for production!
+Intended as a test utility.)
+
+[#recyclers-threadLocal]
+==== Thread-local recycler
+
+[cols="1h,5"]
+|===
+| Module
+| `log4j-kit`
+
+| Name
+| `threadLocal`
+
+| Order
+| `Integer.MAX_VALUE`, if `javax.servlet.Servlet` or `jakarta.servlet.Servlet`
is in the classpath; +
+700, otherwise
+|===
+
+Pools objects in a fixed-size queue stored in a `ThreadLocal`.
+If pool runs out of capacity (see xref:#log4j.recycler.capacity[]), it will
start creating fresh instances for new requests.
+
+Note that it is effectively disabled for servlet environments.
+
+[#recyclers-queue]
+==== Queueing recycler
+
+[cols="1h,5"]
+|===
+| Module
+| `log4j-kit`
+
+| Name
+| `queue`
+
+| Order
+| 800
+|===
+
+Pools objects in a fixed-size `ArrayBlockingQueue` queue.
+If pool runs out of capacity (see xref:#log4j.recycler.capacity[]), it will
start creating fresh instances for new requests.
+
+[#recyclers-jctools]
+==== JCTools MPMC recycler
+
+[cols="1h,5"]
+|===
+| Module
+| `log4j-jctools`
+
+| Name
+| `jctools-mpmc`
+
+| Order
+| 600
+|===
+
+Pools objects in a fixed-size JCTools MPMC queue.
+If pool runs out of capacity (see xref:#log4j.recycler.capacity[]), it will
start creating fresh instances for new requests.
+
[#core-limitations]
=== Limitations
diff --git
a/src/site/antora/modules/ROOT/partials/properties-garbage-collection.adoc
b/src/site/antora/modules/ROOT/partials/properties-garbage-collection.adoc
index 9b0765e653..92a6ebc05d 100644
--- a/src/site/antora/modules/ROOT/partials/properties-garbage-collection.adoc
+++ b/src/site/antora/modules/ROOT/partials/properties-garbage-collection.adoc
@@ -116,3 +116,33 @@ The
link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility
This property specifies the maximum number of primitive arguments to a log
message that will be cached and usually does not need to be changed.
// end::api[]
+
+[id=log4j.recycler.capacity]
+== `log4j.recycler.capacity`
+
+[cols="1h,5"]
+|===
+| Env. variable | LOG4J_RECYCLER_CAPACITY
+| Type | `int`
+| Default value | `2C+1` (`C` denoting the number of available processors)
+|===
+
+Denotes the buffer capacity for a recycler.
+For a queueing recycler, it corresponds to the queue size.
+For a thread local recycler, it corresponds to the per-thread buffer size.
+
+If an invalid capacity is provided (i.e., if the capacity is zero or
negative), the default value will be used.
+
+[id=log4j.recycler.factory]
+== `log4j.recycler.factory`
+
+[cols="1h,5"]
+|===
+| Env. variable | LOG4J_RECYCLER_FACTORY
+| Type | `String`
+| Default value | `null`
+|===
+
+If provided, available recycler factory providers will be sorted in order, and
the first one whose name matching with this property value will be used.
+
+If missing or the selection fails, the default will be used.
