most subclasses of UnsynchronizedAppenderBase do not need a reentry guard

Signed-off-by: ceki <ceki@qos.ch>

Author: ceki

logback-core/src/main/java/ch/qos/logback/core/Appender.java

@@ -17,25 +17,53 @@
 import ch.qos.logback.core.spi.FilterAttachable;
 import ch.qos.logback.core.spi.LifeCycle;
 
+/**
+ * Contract for components responsible for delivering logging events to their
+ * final destination (console, file, remote server, etc.).
+ *
+ * <p>Implementations are typically configured and managed by a LoggerContext.
+ * The type parameter E represents the event type the appender consumes (for
+ * example a log event object). Implementations should honor lifecycle methods
+ * from {@link LifeCycle} and may be {@link ContextAware} and
+ * {@link FilterAttachable} to support contextual information and filtering.</p>
+ *
+ * <p>Concurrency: appenders are generally invoked by multiple threads. Implementations
+ * must ensure thread-safety where applicable (for example when writing to shared
+ * resources). The {@link #doAppend(Object)} method may be called concurrently.</p>
+ *
+ * @param <E> the event type accepted by this appender
+ */
 public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable<E> {
 
     /**
-     * Get the name of this appender. The name uniquely identifies the appender.
+     * Get the name of this appender. The name uniquely identifies the appender
+     * within its context and is used for configuration and lookup.
+     *
+     * @return the appender name, or {@code null} if not set
      */
     String getName();
 
     /**
-     * This is where an appender accomplishes its work. Note that the argument is of
-     * type Object.
-     * 
-     * @param event
+     * This is where an appender accomplishes its work: format and deliver the
+     * provided event to the appender's destination.
+     *
+     * <p>Implementations should apply any configured filters before outputting
+     * the event. Implementations should avoid throwing runtime exceptions;
+     * if an error occurs that cannot be handled internally, a {@link LogbackException}
+     * (or a subtype) may be thrown to indicate a failure during append.</p>
+     *
+     * @param event the event to append; may not be {@code null}
+     * @throws LogbackException if the append fails in a way that needs to be
+     *                          propagated to the caller
      */
     void doAppend(E event) throws LogbackException;
 
     /**
      * Set the name of this appender. The name is used by other components to
-     * identify this appender.
-     * 
+     * identify and reference this appender (for example in configuration or for
+     * status messages).
+     *
+     * @param name the new name for this appender; may be {@code null} to unset
      */
     void setName(String name);
 

logback-core/src/main/java/ch/qos/logback/core/ConsoleAppender.java

@@ -25,6 +25,8 @@
 import ch.qos.logback.core.status.Status;
 import ch.qos.logback.core.status.WarnStatus;
 import ch.qos.logback.core.util.Loader;
+import ch.qos.logback.core.util.ReentryGuard;
+import ch.qos.logback.core.util.ReentryGuardFactory;
 
 /**
  * ConsoleAppender appends log events to <code>System.out</code> or
@@ -100,6 +102,14 @@ public void start() {
         super.start();
     }
 
+    /**
+     * Create a ThreadLocal ReentryGuard to prevent recursive appender invocations.
+     * @return a ReentryGuard instance of type {@link ReentryGuardFactory.GuardType#THREAD_LOCAL THREAD_LOCAL}.
+     */
+    protected ReentryGuard buildReentryGuard() {
+        return ReentryGuardFactory.makeGuard(ReentryGuardFactory.GuardType.THREAD_LOCAL);
+    }
+
     private OutputStream wrapWithJansi(OutputStream targetStream) {
         try {
             addInfo("Enabling JANSI AnsiPrintStream for the console.");

logback-core/src/main/java/ch/qos/logback/core/UnsynchronizedAppenderBase.java

@@ -20,6 +20,8 @@
 import ch.qos.logback.core.spi.FilterAttachableImpl;
 import ch.qos.logback.core.spi.FilterReply;
 import ch.qos.logback.core.status.WarnStatus;
+import ch.qos.logback.core.util.ReentryGuard;
+import ch.qos.logback.core.util.ReentryGuardFactory;
 
 /**
  * Similar to {@link AppenderBase} except that derived appenders need to handle thread
@@ -31,16 +33,13 @@
 abstract public class UnsynchronizedAppenderBase<E> extends ContextAwareBase implements Appender<E> {
 
     protected volatile boolean started = false;
-
-    // using a ThreadLocal instead of a boolean add 75 nanoseconds per
-    // doAppend invocation. This is tolerable as doAppend takes at least a few
-    // microseconds
-    // on a real appender
     /**
      * The guard prevents an appender from repeatedly calling its own doAppend
      * method.
+     *
+     * @since 1.5.21
      */
-    private ThreadLocal<Boolean> guard = new ThreadLocal<Boolean>();
+    private ReentryGuard  reentryGuard;
 
     /**
      * Appenders are named.
@@ -59,23 +58,20 @@ public String getName() {
     static final int ALLOWED_REPEATS = 3;
 
     public void doAppend(E eventObject) {
-        // WARNING: The guard check MUST be the first statement in the
-        // doAppend() method.
+        if (!this.started) {
+            if (statusRepeatCount++ < ALLOWED_REPEATS) {
+                addStatus(new WarnStatus("Attempted to append to non started appender [" + name + "].", this));
+            }
+            return;
+        }
 
         // prevent re-entry.
-        if (Boolean.TRUE.equals(guard.get())) {
+        if (reentryGuard.isLocked()) {
             return;
         }
 
         try {
-            guard.set(Boolean.TRUE);
-
-            if (!this.started) {
-                if (statusRepeatCount++ < ALLOWED_REPEATS) {
-                    addStatus(new WarnStatus("Attempted to append to non started appender [" + name + "].", this));
-                }
-                return;
-            }
+            reentryGuard.lock();
 
             if (getFilterChainDecision(eventObject) == FilterReply.DENY) {
                 return;
@@ -89,7 +85,7 @@ public void doAppend(E eventObject) {
                 addError("Appender [" + name + "] failed to append.", e);
             }
         } finally {
-            guard.set(Boolean.FALSE);
+            reentryGuard.unlock();
         }
     }
 
@@ -103,9 +99,37 @@ public void setName(String name) {
     }
 
     public void start() {
+        this.reentryGuard = buildReentryGuard();
         started = true;
     }
 
+    /**
+     * Create a {@link ReentryGuard} instance used by this appender to prevent
+     * recursive/re-entrant calls to {@link #doAppend(Object)}.
+     *
+     * <p>The default implementation returns a no-op guard produced by
+     * {@link ReentryGuardFactory#makeGuard(ch.qos.logback.core.util.ReentryGuardFactory.GuardType)}
+     * using {@code GuardType.NOP}. Subclasses that require actual re-entry
+     * protection (for example using a thread-local or lock-based guard) should
+     * override this method to return an appropriate {@link ReentryGuard}
+     * implementation.</p>
+     *
+     * <p>Contract/expectations:
+     * <ul>
+     *   <li>Called from {@link #start()} to initialize the appender's guard.</li>
+     *   <li>Implementations should be lightweight and thread-safe.</li>
+     *   <li>Return value must not be {@code null}.</li>
+     * </ul>
+     * </p>
+     *
+     * @return a non-null {@link ReentryGuard} used to detect and prevent
+     *         re-entrant appends. By default this is a no-op guard.
+     * @since 1.5.21
+     */
+    protected ReentryGuard buildReentryGuard() {
+        return ReentryGuardFactory.makeGuard(ReentryGuardFactory.GuardType.NOP);
+    }
+
     public void stop() {
         started = false;
     }

logback-core/src/main/java/ch/qos/logback/core/util/ReentryGuard.java

@@ -0,0 +1,137 @@
+/*
+ * Logback: the reliable, generic, fast and flexible logging framework.
+ *  Copyright (C) 1999-2025, QOS.ch. All rights reserved.
+ *
+ * This program and the accompanying materials are dual-licensed under
+ * either the terms of the Eclipse Public License v1.0 as published by
+ * the Eclipse Foundation
+ *
+ *     or (per the licensee's choosing)
+ *
+ * under the terms of the GNU Lesser General Public License version 2.1
+ * as published by the Free Software Foundation.
+ */
+
+package ch.qos.logback.core.util;
+
+/**
+ * Guard used to prevent re-entrant (recursive) appender invocations on a per-thread basis.
+ *
+ * <p>Implementations are used by appenders and other components that must avoid
+ * recursively calling back into themselves (for example when an error causes
+ * logging while handling a logging event). Typical usage: check {@link #isLocked()}
+ * before proceeding and call {@link #lock()} / {@link #unlock()} around the
+ * guarded region.</p>
+ *
+ * <p>Concurrency: guards operate on a per-thread basis; callers should treat the
+ * guard as thread-local state. Implementations must document their semantics;
+ * the provided {@link ReentryGuardImpl} uses a {@link ThreadLocal} to track the
+ * locked state for the current thread.</p>
+*
+ * @since 1.5.21
+ */
+public interface ReentryGuard {
+
+    /**
+     * Return true if the current thread holds the guard (i.e. is inside a guarded region).
+     *
+     * <p>Implementations typically return {@code false} if the current thread has not
+     * previously called {@link #lock()} or if the stored value is {@code null}.</p>
+     *
+     * @return {@code true} if the guard is locked for the current thread, {@code false} otherwise
+     */
+    boolean isLocked();
+
+    /**
+     * Mark the guard as locked for the current thread.
+     *
+     * <p>Callers must ensure {@link #unlock()} is invoked in a finally block to
+     * avoid leaving the guard permanently locked for the thread.</p>
+     */
+    void lock();
+
+    /**
+     * Release the guard for the current thread.
+     *
+     * <p>After calling {@code unlock()} the {@link #isLocked()} should return
+     * {@code false} for the current thread (unless {@code lock()} is called again).</p>
+     */
+    void unlock();
+
+
+    /**
+     * Default per-thread implementation backed by a {@link ThreadLocal<Boolean>}.
+     *
+     * <p>Semantics: a value of {@link Boolean#TRUE} indicates the current thread
+     * is inside a guarded region. If the ThreadLocal has no value ({@code null}),
+     * {@link #isLocked()} treats this as unlocked (returns {@code false}).</p>
+     *
+     * <p>Note: this implementation intentionally uses {@code ThreadLocal<Boolean>}
+     * to avoid global synchronization. The initial state is unlocked.</p>
+     *
+     * Typical usage:
+     * <pre>
+     * if (!guard.isLocked()) {
+     *   guard.lock();
+     *   try {
+     *     // guarded work
+     *   } finally {
+     *     guard.unlock();
+     *   }
+     * }
+     * </pre>
+     *
+     */
+    class ReentryGuardImpl implements ReentryGuard {
+
+        private ThreadLocal<Boolean> guard = new ThreadLocal<Boolean>();
+
+
+        @Override
+        public boolean isLocked() {
+            // the guard is considered locked if the ThreadLocal contains Boolean.TRUE
+            // note that initially the ThreadLocal contains null
+            return (Boolean.TRUE.equals(guard.get()));
+        }
+
+        @Override
+        public void lock() {
+            guard.set(Boolean.TRUE);
+        }
+
+        @Override
+        public void unlock() {
+            guard.set(Boolean.FALSE);
+        }
+    }
+
+    /**
+     * No-op implementation that never locks. Useful in contexts where re-entrancy
+     * protection is not required.
+     *
+     * <p>{@link #isLocked()} always returns {@code false}. {@link #lock()} and
+     * {@link #unlock()} are no-ops.</p>
+     *
+     * <p>Use this implementation when the caller explicitly wants to disable
+     * reentrancy protection (for example in tests or in environments where the
+     * cost of thread-local checks is undesirable and re-entrancy cannot occur).</p>
+     *
+     */
+    class NOPRentryGuard implements ReentryGuard {
+        @Override
+        public boolean isLocked() {
+            return false;
+        }
+
+        @Override
+        public void lock() {
+            // NOP
+        }
+
+        @Override
+        public void unlock() {
+            // NOP
+        }
+    }
+
+}