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.