LeakPresenceDetector.java — netty Source File

Source Code

/*
 * Copyright 2025 The Netty Project
 *
 * The Netty Project licenses this file to you under the Apache License,
 * version 2.0 (the "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at:
 *
 *   https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */

package io.netty.util;

import io.netty.util.internal.SystemPropertyUtil;

import java.io.Closeable;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.LongAdder;
import java.util.function.Supplier;

/**
 * Alternative leak detector implementation for reliable and performant detection in tests.
 *
 * <h3>Background</h3>
 * <p>
 * The standard {@link ResourceLeakDetector} produces no "false positives", but this comes with tradeoffs. You either
 * get many false negatives because only a small sample of buffers is instrumented, or you turn on paranoid detection
 * which carries a somewhat heavy performance cost with each allocation. Additionally, paranoid detection enables
 * detailed recording of buffer access operations with heavy performance impact. Avoiding false negatives is necessary
 * for (unit, fuzz...) testing if bugs should lead to reliable test failures, but the performance impact can be
 * prohibitive for some tests.
 *
 * <h3>The presence detector</h3>
 * <p>
 * The <i>leak presence detector</i> takes a different approach. It foregoes detailed tracking of allocation and
 * modification stack traces. In return every resource is counted, so there are no false negatives where a leak would
 * not be detected.
 * <p>
 * The presence detector also does not wait for an unclosed resource to be garbage collected before it's reported as
 * leaked. This ensures that leaks are detected promptly and can be directly associated with a particular test, but it
 * can lead to false positives. Tests that use the presence detector must shut down completely <i>before</i> checking
 * for resource leaks. There are also complications with static fields, described below.
 *
 * <h3>Resource Scopes</h3>
 * <p>
 * A resource scope manages all resources of a set of threads over time. On allocation, a resource is assigned to a
 * scope through the {@link #currentScope()} method. When {@link #check()} is called, or the scope is
 * {@link ResourceScope#close() closed}, all resources in that scope must have been released.
 * <p>
 * By default, there is only a single "global" scope, and when {@link #check()} is called, all resources in the entire
 * JVM must have been released. To enable parallel test execution, it may be necessary to use separate scopes for
 * separate tests instead, so that one test can check for its own leaks while another test is still in progress. You
 * can override {@link #currentScope()} to implement this for your test framework.
// ... (302 more lines)