Cache on Opensource internals

The Lock-Free Eviction Queue: Weak Pointers and Sequence Numbers

Jay Hubbert — Sat, 24 Oct 2026 13:10:00 +0000

TL;DR: The eviction queue is a duckdb_moodycamel::ConcurrentQueue of BufferEvictionNode{ weak_ptr<BlockMemory> memory_p; idx_t handle_sequence_number; }. Because the queue stores only a weak pointer, enqueuing a block costs nothing and never keeps a dead block alive — the queue is allowed to accumulate garbage. An entry is stale if the weak pointer has expired (the block was destroyed) or if its sequence number no longer matches the block’s current eviction_seq_num (a newer entry superseded it). Staleness is therefore detectable without taking the block lock. Garbage collection is amortised: a purge runs every 4096 insertions and uses try_dequeue_bulk + enqueue_bulk with a separate producer token, so the survivors land in a sub-queue the consumer token has already walked past and FIFO order is preserved.

The scenario

Eight threads are scanning eight different tables. The memory limit is 4 GB. Every time a scan finishes a block it hands the block back to the pool; every time a scan wants a new block it takes one. Meanwhile, the pool is over its limit and needs to make room.

The pool’s job is to keep a list of blocks it could throw away, in roughly the order it should throw them away. That list has to survive:

concurrency — many threads adding and removing entries at once;
blocks that die — a BlockHandle can be destroyed while its entry is still in the queue, leaving a dangling reference;
duplicate entries — the same block can be enqueued, evicted-and-reloaded, and enqueued again, so the queue can hold several entries for the same block, only one of which is current.

A naive std::queue<shared_ptr<BlockHandle>> fails on all three counts: it needs a lock, and it cannot represent “the block this entry refers to is gone”.

The node: a weak pointer and a version number

Here is the whole type:

 cpp
 
 
// src/include/duckdb/storage/buffer/buffer_pool.hpp:27
struct BufferEvictionNode {
	BufferEvictionNode() {
	}
	BufferEvictionNode(weak_ptr<BlockMemory> block_memory_p, idx_t eviction_seq_num);

	weak_ptr<BlockMemory> memory_p;
	idx_t handle_sequence_number;

	bool IsDeadNode(optional_idx debug_sleep_micros = optional_idx());
};

Two fields. memory_p is a weak pointer to the block’s BlockMemory; handle_sequence_number is a version number.

Why weak? Because the queue must not keep a block alive. If the queue held a shared_ptr, then a block could never be freed while its entry sat in the queue, and the queue would grow without bound as blocks are loaded and unloaded. With a weak_ptr, the entry is allowed to dangle — the entry survives the block, and the purger notices.

Why a sequence number? Because a block can be enqueued more than once. Suppose a block is unpinned (enqueued, sequence 1), then pinned and unpinned again (enqueued, sequence 2). Now the queue holds two entries for the same block. Only the second is current. Without a version, the sweeper would happily unload the block twice, or unload it while somebody had re-pinned it.

The version lives on the block itself:

 cpp
 
 
// src/include/duckdb/storage/buffer/block_handle.hpp:120
	//! Returns the eviction sequence number.
	idx_t GetEvictionSequenceNumber() const {
		return eviction_seq_num.load(std::memory_order_acquire);
	}
	//! Increments the eviction sequence number prior to returning it.
	idx_t NextEvictionSequenceNumber(BlockLock &l) {
		VerifyMutex(l);
		auto new_sequence_number = eviction_seq_num.load(std::memory_order_relaxed) + 1;
		// Publish preceding dead-node accounting to lock-free queue readers.
		eviction_seq_num.store(new_sequence_number, std::memory_order_release);
		return new_sequence_number;
	}

and the declaration carries the invariant in a comment:

 cpp
 
 
// src/include/duckdb/storage/buffer/block_handle.hpp:242
	//! The internal eviction sequence number. Monotonic: it is never reset, so an eviction queue
	//! entry is stale if and only if its sequence number differs from this one. Writers hold the block lock.
	atomic<idx_t> eviction_seq_num;

Monotonic. Never reset. That is the key property. Because the counter only ever goes up, “the entry’s number differs from the block’s current number” is an unambiguous test for “this entry is from an older generation”. No ABA problem, no epoch, no generation list.

Two ways a node dies

The liveness test is short:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:42
BufferEvictionNode::BufferEvictionNode(weak_ptr<BlockMemory> block_memory_p, idx_t eviction_seq_num)
 : memory_p(std::move(block_memory_p)), handle_sequence_number(eviction_seq_num) {
	D_ASSERT(!memory_p.expired());
}

bool BufferEvictionNode::IsDeadNode(optional_idx debug_sleep_micros) {
	auto shared_memory_p = memory_p.lock();
	if (debug_sleep_micros.IsValid()) {
		ThreadUtil::SleepMicroSeconds(debug_sleep_micros.GetIndex());
	}
	if (!shared_memory_p) {
		return true;
	}
	if (handle_sequence_number != shared_memory_p->GetEvictionSequenceNumber()) {
		return true;
	}
	return false;
}

Two death certificates:

!shared_memory_p — the weak pointer could not be upgraded. The BlockMemory was destroyed, so the block is gone entirely. The entry is garbage.
handle_sequence_number != shared_memory_p->GetEvictionSequenceNumber() — the block is alive, but this entry is from an older generation. A newer entry for the same block exists, and that one is the live one.

Note that the second test reads GetEvictionSequenceNumber() with memory_order_acquire while the writer used memory_order_release. That pairing is what makes the test well-defined: if the reader sees the new number, it also sees everything the writer did before storing it.

And note what is not here: no lock. IsDeadNode touches only the weak pointer’s control block and one atomic load. It can be called on a queue full of blocks that other threads are concurrently locking, loading and unloading. The staleness test is entirely lock-free.

The debug_sleep_micros parameter is a debug-only hook: it makes the thread sleep between upgrading the weak pointer and checking the sequence number, so that a race between a block’s destruction and the purger can be provoked on purpose. There is a whole DuckDB setting for it.

The queue

The container is a third-party lock-free MPMC queue:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:61
typedef duckdb_moodycamel::ConcurrentQueue<BufferEvictionNode> eviction_queue_t;

duckdb_moodycamel::ConcurrentQueue is Cameron Desrochers’ implementation, vendored in third_party/concurrentqueue. Its own header describes it as “a C++11 implementation of a multi-producer, multi-consumer lock-free queue”, and points at a write-up of the design.

And DuckDB keeps a no-threads fallback so that single-threaded builds still compile:

 cpp
 
 
// src/include/duckdb/parallel/concurrentqueue.hpp:58
template <typename T>
class ConcurrentQueue {
private:
	//! The standard library queue.
	std::queue<T, std::deque<T>> q;

public:
	//! Default constructor.
	ConcurrentQueue() = default;
	//! Constructor reserving capacity.
	explicit ConcurrentQueue(size_t capacity) {
		q.reserve(capacity);
	}

The real queue is not a ring buffer. It is a linked list of per-producer sub-queues, which is what makes the producer/consumer token trick possible.

Adding to the queue

Here is the enqueue path, from the BufferPool down to the queue:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:274
bool BufferPool::AddToEvictionQueue(BlockLock &lock, shared_ptr<BlockHandle> &handle) {
	auto &memory = handle->GetMemory();
	// Verify the caller passed this block's lock before we mutate any of its state.
	// The block lock is held throughout: Unpin holds it; ConvertToPersistent acquires the
	// (uncontended) lock of the freshly created block before calling.
	memory.VerifyMutex(lock);
	auto &queue = GetEvictionQueueForBlockMemory(memory);

	D_ASSERT(memory.GetReaders() == 0);
	if (memory.HasLiveQueueEntry(lock)) {
		// Count the previous live entry before bumping the sequence number. PurgeIteration
		// reads sequence numbers without the block lock; bumping first could let it see the
		// previous entry as stale and decrement dead_nodes before this matching increment.
		queue.IncrementDeadNodes();
	}

	auto ts = memory.NextEvictionSequenceNumber(lock);

Three things in this excerpt, and all three are about the race between the lock-free purger and this locked writer.

HasLiveQueueEntry tracks whether the block already has an entry in the queue that has not been counted as dead. If it does, the previous entry is about to become stale (we are about to bump the sequence number), so the dead-node counter is incremented now.

The ordering comment is the interesting part:

Count the previous live entry before bumping the sequence number. PurgeIteration reads sequence numbers without the block lock; bumping first could let it see the previous entry as stale and decrement dead_nodes before this matching increment.

This is a genuine race, and the code closes it by ordering the two operations. If we bumped the sequence number first, a concurrent purger could observe the old entry as stale, decide it is dead, and decrement total_dead_nodes — and then our increment would arrive and push the counter up by one, leaving the counter permanently one too high. By counting the dead node first, the counter is momentarily one too low rather than one too high, and the purger’s decrement corrects it.

NextEvictionSequenceNumber is called last, and it bumps the counter that makes the previous entry stale. After this point, the new entry is the only live one.

Then the actual enqueue:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:144
bool EvictionQueue::AddToEvictionQueue(BufferEvictionNode &&node) {
	q.enqueue(std::move(node));
	return ++evict_queue_insertions % INSERT_INTERVAL == 0;
}

One line of real work, and then the amortisation trigger: the queue counts its own insertions and reports “time to purge” every 4096 of them.

The purge

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:154
void EvictionQueue::Purge() {
	// only one thread purges the queue, all other threads early-out
	unique_lock<mutex> guard(purge_lock, std::try_to_lock);
	if (!guard.owns_lock()) {
		return;
	}

	// we purge INSERT_INTERVAL * PURGE_SIZE_MULTIPLIER nodes
	idx_t purge_size = INSERT_INTERVAL * PURGE_SIZE_MULTIPLIER;

	// get an estimate of the queue size as-of now
	idx_t approx_q_size = q.size_approx();

	// early-out, if the queue is not big enough to justify purging
	// - we want to keep the LRU characteristic alive
	if (approx_q_size < purge_size * EARLY_OUT_MULTIPLIER) {
		return;
	}

The purge is not a lock-free operation, and it does not need to be: it is a rare, batch-oriented garbage collection, and it is explicitly serialised. std::try_to_lock means that if another thread is already purging, this thread just gives up — the purge will happen anyway.

The early-out is a heuristic with a stated motive: “we want to keep the LRU characteristic alive”. Purging a queue that is mostly alive means re-inserting most of its nodes, which costs time and disturbs the order. So the purge only runs when the queue is big.

The constants:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:114
private:
	//! We trigger a purge of the eviction queue every INSERT_INTERVAL insertions
	constexpr static idx_t INSERT_INTERVAL = 4096;
	//! We multiply the base purge size by this value.
	constexpr static idx_t PURGE_SIZE_MULTIPLIER = 2;
	//! We multiply the purge size by this value to determine early-outs. This is the minimum queue size.
	//! We never purge below this point.
	constexpr static idx_t EARLY_OUT_MULTIPLIER = 4;
	//! We multiply the approximate alive nodes by this value to test whether our total dead nodes
	//! exceed their allowed ratio. Must be greater than 1.
	constexpr static idx_t ALIVE_NODE_MULTIPLIER = 4;

So: purge every 4096 insertions, purge 8192 nodes at a time, and only bother if the queue has at least 32768 nodes in it.

The bulk purge, and the FIFO trick

Here is the actual garbage collection:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:215
void EvictionQueue::PurgeIteration(const idx_t purge_size) {
	// if this purge is significantly smaller or bigger than the previous purge, then
	// we need to resize the purge_nodes vector. Note that this barely happens, as we
	// purge queue_insertions * PURGE_SIZE_MULTIPLIER nodes
	idx_t previous_purge_size = purge_nodes.size();
	if (purge_size < previous_purge_size / 2 || purge_size > previous_purge_size) {
		purge_nodes.resize(purge_size);
	}

	// Dequeue using consumer token — progresses through sub-queues sequentially
	const idx_t actually_dequeued = q.try_dequeue_bulk(purge_consumer_token, purge_nodes.begin(), purge_size);
	if (actually_dequeued == 0) {
		return;
	}

	idx_t dead_count = 0;
	idx_t alive_count = 0;
	auto raw_sleep_micros = debug_eviction_queue_sleep.load(std::memory_order_relaxed);
	optional_idx debug_sleep_micros = raw_sleep_micros > 0 ? optional_idx(raw_sleep_micros) : optional_idx();
	for (idx_t i = 0; i < actually_dequeued; i++) {
		auto &node = purge_nodes[i];
		if (node.IsDeadNode(debug_sleep_micros)) {
			dead_count++;
		} else {
			// Move alive nodes to the front for bulk re-enqueue
			purge_nodes[alive_count++] = std::move(node);
		}
	}

	total_dead_nodes -= dead_count;

	// Re-enqueue alive nodes via producer token — goes into a dedicated sub-queue
	// that the consumer token has already passed
	if (alive_count > 0) {
		if (!purge_producer_token.valid()) {
			throw OutOfMemoryException("Failed to allocate eviction queue producer");
		}
		q.enqueue_bulk(purge_producer_token, purge_nodes.begin(), alive_count);
	}
}

The algorithm is: dequeue a batch, partition it into dead and alive, and re-enqueue the alive ones.

The partition is the compaction trick: alive nodes are moved to the front of the purge_nodes vector (purge_nodes[alive_count++] = std::move(node)), so the survivors end up packed in [0, alive_count) and can be re-enqueued in one bulk call.

Now the part that deserves a slow look: why a separate producer token?

The ConcurrentQueue in moodycamel’s design is a list of per-producer sub-queues, and a consumer token walks them in a fixed order, remembering which one it was on. If the purger re-enqueued the survivors into the same sub-queue the consumer was about to visit, the survivors would be dequeued again immediately, in a loop, forever. The purger would make no progress.

The fix is to give the purge its own producer token. That token is bound to a different sub-queue — one the consumer token has already walked past. So the survivors are pushed behind the consumer’s current position in the traversal, and the consumer will come back around to them only after it has finished with the sub-queues it has not yet visited.

The result: the purge preserves the queue’s FIFO order. The oldest blocks stay oldest, and the LRU characteristic the comment mentioned is preserved across a GC cycle.

The total_dead_nodes bookkeeping also matters: the purger decrements the counter by exactly the number of dead nodes it removed. That counter is what drives the “purge more aggressively” loop in Purge() — when the dead-to-alive ratio gets bad, the purger keeps going until it either reaches a healthy ratio or runs out of queue.

The eviction sweep itself

For completeness, here is the consumer side — the part that actually unloads blocks:

 cpp
 
 
// src/storage/buffer/buffer_pool.cpp:455
template <typename FN>
void EvictionQueue::IterateUnloadableBlocks(FN fn) {
	auto debug_sleep_micros = debug_eviction_queue_sleep.load(std::memory_order_relaxed);
	for (;;) {
		// get a block to unpin from the queue
		BufferEvictionNode node;
		if (!q.try_dequeue(node)) {
			// we could not dequeue any eviction node, so we try one more time,
			// but more aggressively
			if (!TryDequeueWithLock(node)) {
				return;
			}
		}

		// get a reference to the underlying block pointer
		auto handle = node.memory_p.lock();
		if (debug_sleep_micros > 0) {
			// Debug race conditions regarding the ownership of the BlockMemory.
			// Note that for this to trigger we need at least one purge iteration with the setting active.
			ThreadUtil::SleepMicroSeconds(debug_sleep_micros);
		}
		if (!handle) {
			DecrementDeadNodes();
			continue;
		}

		// we might be able to free this block: grab the mutex and check if we can free it
		auto lock = handle->GetLock();
		if (node.handle_sequence_number != handle->GetEvictionSequenceNumber()) {
			// A newer entry superseded this node: it was counted as dead when that entry was added.
			DecrementDeadNodes();
			continue;
		}

The same sequence-number test appears here, but now it is inside the block lock. The difference matters:

In the purger (lock-free), a mismatch means “this entry is stale, drop it”.
Here (holding the lock), a mismatch means “this entry is stale, drop it — and it was already counted as dead when the newer entry was added”, so the counter is decremented.

And when the entry is current, the block is unloaded, under the lock, and the block loses its queue entry (SetHasLiveQueueEntry(lock, false)) so that a later unpin will re-enqueue it with a fresh sequence number.

Two failure paths are handled with care. If the block cannot be offloaded because there is no temporary directory, the node is re-enqueued and the sweep stops — the block is not lost. And if the unload itself throws, the node is re-enqueued and the exception is rethrown, so a failed unload never leaves a block permanently un-evictable.

Costs and trade-offs

The queue can grow without bound between purges. That is the deliberate trade: a weak_ptr entry costs 16 bytes and never keeps anything alive, so a queue with a million stale entries costs 16 MB and nothing else. The purger is the garbage collector, and it runs on a schedule rather than on every operation.
Purging is O(dead nodes), amortised. Every 4096 insertions, up to 8192 nodes are examined. Each examination is one weak-pointer upgrade (an atomic CAS on the control block) plus one atomic load. There is no per-operation cost beyond the enqueue itself.
The weak-pointer upgrade is not free. memory_p.lock() is an atomic compare-and-swap on the control block, and it will fail for dead nodes. But it is lock-free and wait-free, and it is the only way to know whether the block is still alive.
The sequence number is a uint64_t on the block. It costs 8 bytes per block and one atomic increment per enqueue. In exchange, the purger needs no lock and no epoch-based scheme.
The dead-node counter is approximate by design. It is maintained under a mixture of locked and lock-free operations, and the source comments are explicit about the race and about which way the error is allowed to go. It is used to decide how hard to purge, not for correctness.
The pool is not one queue but several. FileBufferTypeToEvictionQueueTypeIdx maps buffer types onto three queue types — BLOCK/EXTERNAL_FILE (cheap to discard), MANAGED_BUFFER (must be spilled to a temp file), and TINY_BUFFER (last resort) — and the sweeper drains them in that order. MANAGED_BUFFER alone is split into six queues so that the radix-partitioned row-group allocator can keep a partition’s blocks together. All of that priority lives in which queue a block goes into, not in the queue algorithm itself.
The debug sleep hook exists because these races are real. IsDeadNode takes an optional sleep between upgrading the weak pointer and reading the sequence number, precisely so a test can widen that window and check that the accounting still balances.

The bottom line

The eviction queue is a good example of a design where the data structure is dumb and the protocol is clever. The queue itself is a general-purpose lock-free MPMC container that knows nothing about blocks. All the block-specific intelligence lives in two fields of the node: a weak pointer, so the queue never keeps anything alive, and a monotonic version number, so a stale entry can be recognised without a lock.

The version number is the trick worth stealing. A weak pointer alone tells you “the block is gone”. A weak pointer plus a monotonically increasing per-block counter tells you “this entry is either from a dead block or from a previous generation of a live one” — and both of those questions can be answered with two atomic operations and no lock. No epochs, no hazard pointers, no generation lists.

The second trick worth stealing is the separate producer token. Garbage collection that re-inserts survivors into the same queue it is draining is a livelock waiting to happen; giving the collector its own producer token so the survivors land behind the consumer’s current position is a two-line fix that preserves the queue’s ordering guarantees.

And the general lesson about counters: DuckDB maintains a total_dead_nodes counter across a boundary between locked and lock-free code, and the source comments spend more words explaining which way the error is allowed to go than the arithmetic itself. When a counter is only a heuristic, say so — loudly — and decide deliberately whether it may over- or under-count. The decision is written down: under-count first, let the purger’s decrement fix it up. That is a much better failure mode than the opposite.

Pinning Is Ownership: DuckDB's Buffer Handle Is a shared_ptr

Jay Hubbert — Sat, 24 Oct 2026 12:40:00 +0000

TL;DR: In DuckDB, “pinning” a block means holding a shared_ptr to it. A BufferHandle owns a shared_ptr<BlockHandle>; the BlockHandle owns a shared_ptr<BlockMemory>; and the BlockMemory is the only place the actual FileBuffer bytes live. While a reader holds the handle, the bytes cannot be destroyed, so the block cannot be evicted underneath it. The readers atomic counter is not the safety mechanism — it is an advisory signal that lets the eviction sweeper skip pinned blocks without taking a lock. The safety comes free from the ownership graph.

The scenario

You run a query over a table that is much bigger than your memory limit:

 sql
 
SELECT sum(o_totalprice) FROM orders;

The buffer pool is under pressure. The eviction sweeper is running, deciding which blocks to throw out to make room for the next one. Meanwhile, the scan is holding several blocks open and is about to read a DECIMAL out of one of them.

The question this article is about is narrow and important: how does DuckDB guarantee that the eviction sweeper cannot pull the rug out from under that read?

The naive answer — “it keeps a counter of active readers and refuses to evict a block with a non-zero count” — is how a lot of buffer managers work, and it is subtly wrong. A counter is a hint. Between the moment the sweeper reads the counter and the moment it acts on it, the count can change. Any design that relies on the counter for correctness has a race in it.

DuckDB does not rely on the counter for correctness. It relies on ownership.

The ownership chain

Start at the top. This is the entire BufferHandle class:

 cpp
 
 
// src/include/duckdb/storage/buffer/buffer_handle.hpp:53
	const shared_ptr<BlockHandle> &GetBlockHandle() const {
		return handle;
	}

private:
	//! The block handle
	shared_ptr<BlockHandle> handle;
	//! The managed buffer node
	optional_ptr<FileBuffer> node;

Two members. handle is a shared_ptr<BlockHandle> — a shared ownership handle to the block’s metadata. node is a raw optional_ptr<FileBuffer> — a non-owning pointer to the bytes.

That split is the whole design. The handle owns the block; the block owns the bytes; the handle merely points at the bytes. The pointer is a convenience (it is what Ptr() returns), not a lifetime guarantee.

Here is the BlockHandle side:

 cpp
 
 
// src/include/duckdb/storage/buffer/block_handle.hpp:292
	//! Returns a const reference to the memory of a block.
	const BlockMemory &GetMemory() const {
		return memory;
	}
	//! Returns a reference to the memory of a block.
	BlockMemory &GetMemory() {
		return memory;
	}
	//! Returns a weak pointer to the memory of a block.
	weak_ptr<BlockMemory> GetMemoryWeak() const {
		return weak_ptr<BlockMemory>(memory_p);
	}

and the members at the bottom of the class:

 cpp
 
 
// src/include/duckdb/storage/buffer/block_handle.hpp:324
	//! Pointer to the underlying memory of the block.
	const shared_ptr<BlockMemory> memory_p;
	//! Memory for fast access to the block memory.
	BlockMemory &memory;

There are two views of the same BlockMemory:

memory_p is a shared_ptr<BlockMemory> — the owner.
memory is a BlockMemory & — a raw reference, for fast access without an atomic refcount bump.

And BlockMemory is where the bytes actually live:

 cpp
 
 
// src/include/duckdb/storage/buffer/block_handle.hpp:234
	//! The number of concurrent readers. Writers hold the block lock; reads may be unlocked.
	atomic<int32_t> readers;
	//! The memory tag.
	const MemoryTag tag;
	//! The file buffer type.
	const FileBufferType buffer_type;
	//! A pointer to the loaded data, if any.
	unique_ptr<FileBuffer> buffer;

buffer is a unique_ptr<FileBuffer>. That is the object that owns the memory the query is reading.

So the chain is:

text

BufferHandle
 └─ shared_ptr<BlockHandle>
 └─ shared_ptr<BlockMemory> (memory_p)
 └─ unique_ptr<FileBuffer> (buffer)
 └─ the actual bytes

Three levels of ownership, and every level is a shared_ptr or a unique_ptr. When the last shared_ptr to the BlockMemory goes away, the BlockMemory is destroyed, its unique_ptr<FileBuffer> is destroyed, and the bytes are released. There is no other path to freeing the bytes, because buffer is private to BlockMemory and there is exactly one BlockMemory per block.

This is the invariant: the bytes cannot be freed while any BufferHandle exists, because a BufferHandle transitively holds the only shared_ptr chain to them.

Why the readers counter is only a hint

Here is the counter’s implementation:

 cpp
 
 
// src/include/duckdb/storage/buffer/block_handle.hpp:79
	//! Increments the number of readers prior to returning it.
	int32_t IncrementReaders(BlockLock &l) {
		VerifyMutex(l);
		// Tiny buffers do not decrement on unpin, so their reader count can wrap.
		auto new_readers = static_cast<int32_t>(static_cast<uint32_t>(readers.load(std::memory_order_relaxed)) + 1);
		readers.store(new_readers, std::memory_order_relaxed);
		return new_readers;
	}
	//! Decrements the number of readers prior to returning it.
	int32_t DecrementReaders(BlockLock &l) {
		VerifyMutex(l);
		auto new_readers = static_cast<int32_t>(static_cast<uint32_t>(readers.load(std::memory_order_relaxed)) - 1);
		readers.store(new_readers, std::memory_order_relaxed);
		return new_readers;
	}

Two things to notice.

The comment about tiny buffers. “Tiny buffers do not decrement on unpin, so their reader count can wrap.” A TINY_BUFFER is a small allocation that is not managed by the pool; it is never unloaded, so the counter would only ever grow. Rather than special-case it, the code explicitly allows the int32_t to wrap around by doing the arithmetic in uint32_t and casting back. This is a deliberate decision to make a hint wrong rather than to add a branch to a hot path. And it is safe precisely because the hint is not load-bearing for correctness.

The memory ordering is relaxed. The counter is not a synchronisation primitive. It is a number that is approximately right. If two threads increment it concurrently, the result is some number that is not exactly the number of readers — and that is fine, because the counter is only used to answer “should I bother looking at this block?”.

And here is where it is consumed:

 cpp
 
 
// src/storage/buffer/block_handle.cpp:105
CanUnloadResult BlockMemory::CanUnload() const {
	if (GetState() == BlockState::BLOCK_UNLOADED) {
		// The block has already been unloaded.
		return CanUnloadResult::ALREADY_UNLOADED;
	}
	if (GetReaders() > 0) {
		// There are active readers.
		return CanUnloadResult::PINNED;
	}
	if (BlockId() >= MAXIMUM_BLOCK && MustWriteToTemporaryFile() && !GetBufferManager().HasTemporaryDirectory()) {
		// The block memory cannot be destroyed upon eviction/unpinning.
		// In order to unload this block we need to write it to a temporary buffer.
		// However, no temporary directory is specified, hence, we cannot unload.
		return CanUnloadResult::NO_TEMP_DIRECTORY;
	}
	return CanUnloadResult::CAN_UNLOAD;
}

GetReaders() > 0 → PINNED. The sweeper skips it.

But how is this safe? The answer is that the sweeper does not free the bytes by destroying the FileBuffer out from under a reader. It frees them by unloading the block — and unloading requires taking the block’s lock, and the block’s state transition to BLOCK_UNLOADED is guarded by that lock.

The real safety net is the combination:

A reader holds a shared_ptr chain to the BlockMemory, so the BlockMemory — and therefore the FileBuffer — cannot be destroyed.
The sweeper’s decision to unload is made under the block lock.
A reader that is about to read takes the block lock when it loads or increments the reader count, so it cannot race with an unload.

The counter, meanwhile, tells the sweeper “don’t even bother taking the lock for this one”. It is an optimisation. If the counter were wrong, the sweeper would take the lock, see the true state, and do the right thing anyway.

Pinning: the double-checked load

Here is Pin, the function that turns a BlockHandle into a BufferHandle:

 cpp
 
 
// src/storage/standard_buffer_manager.cpp:369
BufferHandle StandardBufferManager::Pin(const QueryContext &context, shared_ptr<BlockHandle> &handle) {
	// we need to be careful not to return the BufferHandle to this block while holding the BlockHandle's lock
	// as exiting this function's scope may cause the destructor of the BufferHandle to be called while holding the lock
	// the destructor calls Unpin, which grabs the BlockHandle's lock again, causing a deadlock
	BufferHandle buf;

	idx_t required_memory;
	auto &block_memory = handle->GetMemory();
	{
		// lock the block
		auto lock = block_memory.GetLock();
		// check if the block is already loaded
		if (block_memory.GetState() == BlockState::BLOCK_LOADED) {
			// the block is loaded, increment the reader count and set the BufferHandle
			buf = handle->Load(lock, context);
		}
		required_memory = block_memory.GetMemoryUsage();
	}

	if (buf.IsValid()) {
		return buf; // the block was already loaded, return it without holding the BlockHandle's lock
	}

Read the comment at the top. It is a self-deadlock warning, and it is the most instructive line in the whole file:

we need to be careful not to return the BufferHandle to this block while holding the BlockHandle’s lock as exiting this function’s scope may cause the destructor of the BufferHandle to be called while holding the lock the destructor calls Unpin, which grabs the BlockHandle’s lock again, causing a deadlock

This is the price of the ownership design. BufferHandle’s destructor calls Unpin, which takes the block lock. If the handle were returned while the lock was held, the temporary’s destructor would run at the end of the scope — with the lock still held — and Unpin would try to take the same non-recursive std::mutex again. Boom.

So Pin deliberately returns the handle outside the lock’s scope. The lock is acquired in an inner block { ... } precisely so that it is released before the return.

Continue reading the function and you see the classic double-checked pattern:

 cpp
 
 
// src/storage/standard_buffer_manager.cpp:392
	// evict blocks until we have space for the current block
	unique_ptr<FileBuffer> reusable_buffer;
	auto reservation =
	 EvictBlocksOrThrow(context, block_memory.GetMemoryTag(), required_memory, &reusable_buffer,
	 "failed to pin block of size %s%s", StringUtil::BytesToHumanReadableString(required_memory));

	// lock the handle again and repeat the check (in case anybody loaded in the meantime)
	auto lock = block_memory.GetLock();
	// check if the block is already loaded
	if (block_memory.GetState() == BlockState::BLOCK_LOADED) {
		// the block is loaded, increment the reader count and return a pointer to the handle
		reservation.Resize(0);
		buf = handle->Load(lock, context);
	} else {

Between releasing the lock and re-acquiring it, we went and evicted blocks to make room — which takes an unbounded amount of time and releases the lock entirely. Another thread may have loaded the same block in the meantime. So the state is checked again under the lock. If somebody beat us to it, the memory reservation we took is refunded (reservation.Resize(0)) and we just take a reader count on the already-loaded block.

The reservation refund is a nice touch: the memory is charged to the pool the moment we decide we might need it, and un-charged the moment we discover we don’t. The charging is an RAII token, so the refund is a single call.

And here is the actual load:

 cpp
 
 
// src/storage/buffer/block_handle.cpp:214
BufferHandle BlockHandle::Load(BlockLock &l, QueryContext context, unique_ptr<FileBuffer> reusable_buffer) {
	memory.VerifyMutex(l);
	if (memory.GetState() == BlockState::BLOCK_LOADED) {
		// The block has already been loaded.
		D_ASSERT(memory.GetBuffer());
		memory.IncrementReaders(l);
		return BufferHandle(shared_from_this(), memory.GetBuffer());
	}

	if (!memory.CanReload()) {
		// the buffer was destroyed upon unpin/evict, or the handle was replaced and its disk block
		// may be rewritten in place - the caller must re-resolve the block id
		return BufferHandle();
	}

BufferHandle(shared_from_this(), memory.GetBuffer()). The shared_from_this() is the crux: the BlockHandle hands out a shared_ptr to itself, and the BufferHandle stores it. That is what makes the whole chain hold.

Note also memory.IncrementReaders(l) — the counter is bumped here, under the block lock, at the same moment the handle is created. So the counter and the ownership are established atomically with respect to the lock. A sweeper that takes the lock and sees readers == 0 genuinely knows that at that instant no reader exists.

Unpinning

 cpp
 
 
// src/storage/standard_buffer_manager.cpp:459
void StandardBufferManager::Unpin(shared_ptr<BlockHandle> &handle) {
	bool purge = false;
	auto &block_memory = handle->GetMemory();
	{
		auto lock = block_memory.GetLock();
		if (!block_memory.GetBuffer(lock) || block_memory.GetBufferType() == FileBufferType::TINY_BUFFER) {
			return;
		}
		D_ASSERT(block_memory.GetReaders() > 0);
		auto new_readers = block_memory.DecrementReaders(lock);
		if (new_readers == 0) {
			VerifyZeroReaders(lock, handle);
			if (block_memory.MustAddToEvictionQueue()) {
				purge = buffer_pool.AddToEvictionQueue(lock, handle);
			} else {
				block_memory.Unload(lock);
			}
		}
	}

	// We do not have to keep the handle locked while purging.
	if (purge) {
		PurgeQueue(*handle);
	}
}

Three things:

Tiny buffers return early. They were never added to the pool, so there is nothing to unpin. (And, as we saw, that is why their reader counter is allowed to wrap.)
When the count hits zero, the block goes on the eviction queue. Note the order: the count is decremented first, and only then is the block offered to the sweeper. That ordering is what makes the counter a valid hint.
The purge happens outside the lock. The comment says it: “We do not have to keep the handle locked while purging.” A purge is a full sweep of the eviction queue — it can take a while, and holding the block’s lock through it would block every other thread that wants to pin the same block. The purge flag is set under the lock; the call happens after the lock is released.

And here is where the handle gives up its ownership:

 cpp
 
 
// src/storage/buffer/buffer_handle.cpp:35
void BufferHandle::Destroy() {
	if (!handle || !IsValid()) {
		return;
	}
	handle->GetMemory().GetBufferManager().Unpin(handle);
	handle.reset();
	node = nullptr;
}

Unpin first, then handle.reset(). The reset is what drops the shared_ptr — and if that was the last reference to the BlockMemory, the bytes are freed right there. If the block was still in use elsewhere, the shared_ptr count simply stays above zero and the bytes survive.

Note the order: Unpin before reset. If it were the other way round, the BlockMemory could be destroyed before Unpin had decremented the counter, and Unpin would be touching freed memory.

Costs and trade-offs

The reference counting is an atomic increment on the hot path. Every Pin that finds the block already loaded does one shared_from_this() (an atomic increment on the BlockHandle’s control block) and one shared_ptr copy into the BufferHandle. Every Unpin does the matching decrement. On a hot scan, that is a couple of atomic read-modify-writes per block — cheap, but not free. It is worth it because it replaces a correctness mechanism (locking, reference counting by hand, hazard pointers) with a safety mechanism (the type system).
shared_ptr is not free in code size either. The enable_shared_from_this base class on BlockHandle, the weak_ptr accessor for the eviction queue, the ColumnBindingReplacer-style plumbing — all of it exists because the block is a shared_ptr citizen.
The readers counter is still worth keeping. It is an atomic<int32_t> with relaxed ordering, and it lets the eviction sweeper skip pinned blocks without taking a lock and without constructing a shared_ptr from the weak one. On a pool with thousands of blocks, most of which may be pinned, that saves a lot of lock traffic.
The counter is allowed to lie. Tiny buffers wrap it. The relaxed ordering means concurrent increments can lose a count. Both are fine because nothing depends on its exactness. This is the design paying off: an approximate counter is cheap and safe, and a precise counter would need a lock.
The Pin path takes the block lock at least once and often twice. The double-checked pattern exists because the eviction step in between is slow. If the block was already loaded, only the first lock is taken.
The deadlock hazard is real and is handled by a comment and by scope. Returning a handle whose destructor takes the same lock is the kind of bug you find in production once. The fix here — an inner scope — is subtle enough to deserve the three-line comment that explains it.

The bottom line

There are two ways to keep a block alive while someone reads it.

The first is a counter: “readers: 3, do not evict”. The second is ownership: “here is a shared_ptr; the memory is yours until you let go of it”. The first requires every participant to agree on the protocol and to update the counter at exactly the right moment; the second requires nothing but the discipline to use shared_ptr correctly.

DuckDB uses the second for safety and the first for speed, and it is explicit about which is which. The readers counter is relaxed, is allowed to wrap, and is consulted only to decide whether to bother taking a lock. The shared_ptr chain is the actual guarantee: BufferHandle → BlockHandle → BlockMemory → FileBuffer → the bytes, with a shared_ptr at every level that has a lifetime to protect.

The general lesson: if you need a lock to make your data structure safe, you probably have the wrong data structure. A lock-free shared_ptr is not as free as a raw pointer, but it is free enough, and it buys you the freedom to let the sweeper guess wrong occasionally without corrupting anything.