Why Netty Introduced FastThreadLocal and How It Works

FastThreadLocal Background and Principle

Although JDK already provides ThreadLocal, Netty created FastThreadLocal (ftl) to avoid the hash‑collision overhead of ThreadLocalMap by using a simple indexed array.

In a Java thread, each thread holds a ThreadLocalMap instance only when a ThreadLocal variable is first accessed. The map resolves hash collisions via linear probing, which can degrade performance under heavy collisions.

FastThreadLocal eliminates hash collisions by assigning each ftl instance a unique index stored in an array; the index is generated atomically.

When ftl.get() is called, the value is retrieved directly from the array via return array[index].

Implementation Source Code Analysis

UnpaddedInternalThreadLocalMap Main Fields

static final ThreadLocal<InternalThreadLocalMap> slowThreadLocalMap = new ThreadLocal<InternalThreadLocalMap>();
static final AtomicInteger nextIndex = new AtomicInteger();
Object[] indexedVariables;

The indexedVariables array stores ftl values directly; nextIndex provides a unique index for each ftl instance.

InternalThreadLocalMap Analysis

// marker for unused slots
public static final Object UNSET = new Object();
/**
 * BitSet used to mark whether a FastThreadLocal has registered a cleaner.
 */
private BitSet cleanerFlags;
private InternalThreadLocalMap() {
    super(newIndexedVariableTable());
}
private static Object[] newIndexedVariableTable() {
    Object[] array = new Object[32];
    Arrays.fill(array, UNSET);
    return array;
}

FastThreadLocal stores the actual variable value in the array, not an entry, which differs from JDK ThreadLocal.

Note: FastThreadLocal saves the variable value directly, not an entry, unlike JDK ThreadLocal.

FastThreadLocalThread Implementation

public class FastThreadLocalThread extends Thread {
    private final boolean cleanupFastThreadLocals;
    private InternalThreadLocalMap threadLocalMap;
    public final InternalThreadLocalMap threadLocalMap() {
        return threadLocalMap;
    }
    public final void setThreadLocalMap(InternalThreadLocalMap threadLocalMap) {
        this.threadLocalMap = threadLocalMap;
    }
}

FastThreadLocalThread aggregates its own InternalThreadLocalMap, allowing ftl variables to be accessed directly from the thread.

FastThreadLocal Property and Instantiation

private final int index;
public FastThreadLocal() {
    index = InternalThreadLocalMap.nextVariableIndex();
}

Each ftl instance receives a unique index from InternalThreadLocalMap.nextVariableIndex(), ensuring the array does not need to grow abruptly.

get() Method Implementation

public final V get() {
    InternalThreadLocalMap threadLocalMap = InternalThreadLocalMap.get(); // 1
    Object v = threadLocalMap.indexedVariable(index); // 2
    if (v != InternalThreadLocalMap.UNSET) {
        return (V) v;
    }
    V value = initialize(threadLocalMap); // 3
    registerCleaner(threadLocalMap); // 4
    return value;
}

Step 1 obtains the thread‑local map (fast for FastThreadLocalThread, slow otherwise). Step 2 reads the value from the indexed array. If the slot is UNSET, the value is initialized and a cleaner may be registered.

InternalThreadLocalMap.get() and slowGet()

public static InternalThreadLocalMap get() {
    Thread thread = Thread.currentThread();
    if (thread instanceof FastThreadLocalThread) {
        return fastGet((FastThreadLocalThread) thread);
    } else {
        return slowGet();
    }
}
private static InternalThreadLocalMap slowGet() {
    ThreadLocal<InternalThreadLocalMap> slowThreadLocalMap = UnpaddedInternalThreadLocalMap.slowThreadLocalMap;
    InternalThreadLocalMap ret = slowThreadLocalMap.get();
    if (ret == null) {
        ret = new InternalThreadLocalMap();
        slowThreadLocalMap.set(ret);
    }
    return ret;
}

Ordinary threads fall back to a JDK ThreadLocal ( slowThreadLocalMap) to hold an InternalThreadLocalMap, which then provides the indexed array.

registerCleaner Implementation (Netty 4.1.34)

private void registerCleaner(final InternalThreadLocalMap threadLocalMap) {
    Thread current = Thread.currentThread();
    if (FastThreadLocalThread.willCleanupFastThreadLocals(current) || threadLocalMap.isCleanerFlagSet(index)) {
        return;
    }
    threadLocalMap.setCleanerFlag(index);
    // The ObjectCleaner registration is commented out in this version.
}

Cleaner registration is disabled in this Netty version, leaving only manual cleanup.

Performance Degradation in Ordinary Threads

If a thread is not a FastThreadLocalThread, FastThreadLocal degrades to the JDK ThreadLocal behavior because the thread lacks an InternalThreadLocalMap. The value is then fetched via the slow path described above.

FastThreadLocal Resource Recycling Mechanism

Netty provides three cleanup strategies:

Automatic (wrapped Runnable) : FastThreadLocal is cleared after a FastThreadLocalRunnable finishes.

Manual : Users call remove() on FastThreadLocal or its map when appropriate.

Cleaner‑based (commented out) : A Cleaner would release resources when the thread becomes unreachable, but this code is disabled in version 4.1.34.

FastThreadLocal Usage in Netty

The most important use case is ByteBuf allocation. Each thread holds a PoolArena; when a ByteBuf is needed, the thread first allocates from its own arena, falling back to a global arena if necessary.

PoolThreadLocalCache (extends FastThreadLocal)

final class PoolThreadLocalCache extends FastThreadLocal<PoolThreadCache> {
    @Override
    protected synchronized PoolThreadCache initialValue() {
        final PoolArena<byte[]> heapArena = leastUsedArena(heapArenas);
        final PoolArena<ByteBuffer> directArena = leastUsedArena(directArenas);
        Thread current = Thread.currentThread();
        if (useCacheForAllThreads || current instanceof FastThreadLocalThread) {
            return new PoolThreadCache(heapArena, directArena, tinyCacheSize, smallCacheSize, normalCacheSize,
                    DEFAULT_MAX_CACHED_BUFFER_CAPACITY, DEFAULT_CACHE_TRIM_INTERVAL);
        }
        return new PoolThreadCache(heapArena, directArena, 0, 0, 0, 0, 0);
    }
}

This cache leverages FastThreadLocal to keep per‑thread memory pools, dramatically reducing contention and improving allocation efficiency.