深入理解 postgresql buffer usage_count

/* 源文件：src/include/storage/buf_internals.h:29-46 */

/*
 * Buffer state is a single 32-bit variable where following data is combined.
 *
 * - 18 bits refcount
 * - 4 bits usage count
 * - 10 bits of flags
 */
#define BUF_REFCOUNT_ONE 1
#define BUF_REFCOUNT_MASK ((1U << 18) - 1)
#define BUF_USAGECOUNT_MASK 0x003C0000U
#define BUF_USAGECOUNT_ONE (1U << 18)
#define BUF_USAGECOUNT_SHIFT 18
#define BUF_FLAG_MASK 0xFFC00000U

/* 源文件：src/include/storage/buf_internals.h:48-50 */

/* Get refcount and usagecount from buffer state */
#define BUF_STATE_GET_REFCOUNT(state) ((state) & BUF_REFCOUNT_MASK)
#define BUF_STATE_GET_USAGECOUNT(state) (((state) & BUF_USAGECOUNT_MASK) >> BUF_USAGECOUNT_SHIFT)

/* 源文件：src/include/storage/buf_internals.h:70-77 */

/*
 * The maximum allowed value of usage_count represents a tradeoff between
 * accuracy and speed of the clock-sweep buffer management algorithm.  A
 * large value (comparable to NBuffers) would approximate LRU semantics.
 * But it can take as many as BM_MAX_USAGE_COUNT+1 complete cycles of
 * clock sweeps to find a free buffer, so in practice we don't want the
 * value to be very large.
 */
#define BM_MAX_USAGE_COUNT	5

/* 源文件：src/include/storage/buf_internals.h:182-193 */

typedef struct BufferDesc
{
    BufferTag       tag;              /* 缓冲区包含的页面 ID */
    int             buf_id;           /* 缓冲区索引号 (从 0 开始) */
    pg_atomic_uint32 state;           /* 包含 flags、refcount 和 usagecount */
    int             wait_backend_pid; /* 等待 pin count 的后端 PID */
    int             freeNext;         /* freelist 链表中的链接 */
    LWLock          content_lock;     /* 访问缓冲区内容的锁 */
} BufferDesc;

/* 源文件：src/backend/storage/buffer/freelist.c:29-61 */

typedef struct
{
    slock_t         buffer_strategy_lock;     /* 自旋锁保护 */

    /* 时钟指针：下一个要考虑的缓冲区索引 */
    pg_atomic_uint32 nextVictimBuffer;

    int             firstFreeBuffer;  /* 空闲缓冲区链表头 */
    int             lastFreeBuffer;   /* 空闲缓冲区链表尾 */

    /* 统计信息 */
    uint32          completePasses;   /* 完整扫描的周期数 */
    pg_atomic_uint32 numBufferAllocs; /* 上次重置后分配的缓冲区数 */

    int             bgwprocno;        /* 后台写进程号 */
} BufferStrategyControl;

/* 源文件：src/backend/storage/buffer/freelist.c:112-169 */

static inline uint32
ClockSweepTick(void)
{
    uint32 victim;

    /*
     * 原子性地将时钟指针向前移动一位
     * 如果多个进程同时执行，可能导致缓冲区返回顺序略有偏差
     */
    victim = pg_atomic_fetch_add_u32(&StrategyControl->nextVictimBuffer, 1);

    if (victim >= NBuffers)
    {
        uint32 originalVictim = victim;
        victim = victim % NBuffers;  /* 环绕处理 */

        /* 如果是导致环绕的进程，递增 completePasses */
        if (victim == 0)
        {
            // ... 获取自旋锁并递增 completePasses ...
            StrategyControl->completePasses++;
        }
    }
    return victim;
}

/* 源文件：src/backend/storage/buffer/freelist.c:315-358 */

/* 空闲链表为空时，执行时钟扫描算法 */
trycounter = NBuffers;
for (;;)
{
    buf = GetBufferDescriptor(ClockSweepTick());

    /*
     * 如果缓冲区被 pin 或 usagecount 非零，无法使用
     * 递减 usagecount（如果未被 pin）并继续扫描
     */
    local_buf_state = LockBufHdr(buf);

    if (BUF_STATE_GET_REFCOUNT(local_buf_state) == 0)
    {
        if (BUF_STATE_GET_USAGECOUNT(local_buf_state) != 0)
        {
            /* 递减 usagecount，给予"第二次机会" */
            local_buf_state -= BUF_USAGECOUNT_ONE;
            trycounter = NBuffers;  /* 重置计数器 */
        }
        else
        {
            /* 找到可用缓冲区 */
            if (strategy != NULL)
                AddBufferToRing(strategy, buf);
            *buf_state = local_buf_state;
            return buf;
        }
    }
    else if (--trycounter == 0)
    {
        /* 所有缓冲区都被 pin，报错 */
        UnlockBufHdr(buf, local_buf_state);
        elog(ERROR, "no unpinned buffers available");
    }
    UnlockBufHdr(buf, local_buf_state);
}

/* 源文件: src/backend/storage/buffer/bufmgr.c:1692-1771 */
static bool
PinBuffer(BufferDesc *buf, BufferAccessStrategy strategy)
{
    // ... 省略前序代码 ...

    old_buf_state = pg_atomic_read_u32(&buf->state);
    for (;;)
    {
        if (old_buf_state & BM_LOCKED)
            old_buf_state = WaitBufHdrUnlocked(buf);

        buf_state = old_buf_state;

        /* 增加 refcount */
        buf_state += BUF_REFCOUNT_ONE;

        if (strategy == NULL)
        {
            /* 默认情况：除非已达最大值，否则增加 usagecount */
            if (BUF_STATE_GET_USAGECOUNT(buf_state) < BM_MAX_USAGE_COUNT)
                buf_state += BUF_USAGECOUNT_ONE;
        }
        else
        {
            /*
             * 环形缓冲区不应淘汰其他缓冲区。
             * 因此我们不让 usagecount 超过 1。
             */
            if (BUF_STATE_GET_USAGECOUNT(buf_state) == 0)
                buf_state += BUF_USAGECOUNT_ONE;
        }

        if (pg_atomic_compare_exchange_u32(&buf->state, &old_buf_state,
                                           buf_state))
        {
            result = (buf_state & BM_VALID) != 0;
            VALGRIND_MAKE_MEM_DEFINED(BufHdrGetBlock(buf), BLCKSZ);
            break;
        }
    }
    // ... 省略后续代码 ...
}

/* 源文件: src/backend/storage/buffer/bufmgr.c:1422-1428 */
/*
 * 我们也重置 usage_count，因为旧内容的任何最近使用
 * 都不再相关。（usage_count 从 1 开始，以便缓冲区
 * 可以在一次时钟扫描传递中存活。）
 */
buf_state &= ~(BM_VALID | BM_DIRTY | BM_JUST_DIRTIED |
               BM_CHECKPOINT_NEEDED | BM_IO_ERROR | BM_PERMANENT |
               BUF_USAGECOUNT_MASK);
if (relpersistence == RELPERSISTENCE_PERMANENT || forkNum == INIT_FORKNUM)
    buf_state |= BM_TAG_VALID | BM_PERMANENT | BUF_USAGECOUNT_ONE;
else
    buf_state |= BM_TAG_VALID | BUF_USAGECOUNT_ONE;

/* 源文件：src/backend/storage/buffer/bufmgr.c:1840-1890 */
static void
UnpinBuffer(BufferDesc *buf, bool fixOwner)
{
    // ... 省略前序代码 ...

    old_buf_state = pg_atomic_read_u32(&buf->state);
    for (;;)
    {
        if (old_buf_state & BM_LOCKED)
            old_buf_state = WaitBufHdrUnlocked(buf);

        buf_state = old_buf_state;

        /* 仅减少 refcount，不影响 usagecount */
        buf_state -= BUF_REFCOUNT_ONE;

        if (pg_atomic_compare_exchange_u32(&buf->state, &old_buf_state,
                                           buf_state))
            break;
    }
    // ... 省略后续代码 ...
}

/* 源文件：src/backend/storage/buffer/bufmgr.c:1726-1733 */

else
{
    /*
     * Ring buffers shouldn't evict others from pool.  Thus we
     * don't make usagecount more than 1.
     */
    if (BUF_STATE_GET_USAGECOUNT(buf_state) == 0)
        buf_state += BUF_USAGECOUNT_ONE;
}

/* 源文件：src/backend/storage/buffer/localbuf.c:141-148 */

/* this part is equivalent to PinBuffer for a shared buffer */
if (LocalRefCount[b] == 0)
{
    if (BUF_STATE_GET_USAGECOUNT(buf_state) < BM_MAX_USAGE_COUNT)
    {
        buf_state += BUF_USAGECOUNT_ONE;
        pg_atomic_unlocked_write_u32(&bufHdr->state, buf_state);
    }
}

/* 源文件：src/backend/storage/buffer/freelist.c:634-651 */

/*
 * If usage_count is 0 or 1 then the buffer is fair game (we expect 1,
 * since our own previous usage of the ring element would have left it
 * there, but it might've been decremented by clock sweep since then). A
 * higher usage_count indicates someone else has touched the buffer, so we
 * shouldn't re-use it.
 */
buf = GetBufferDescriptor(bufnum - 1);
local_buf_state = LockBufHdr(buf);
if (BUF_STATE_GET_REFCOUNT(local_buf_state) == 0
    && BUF_STATE_GET_USAGECOUNT(local_buf_state) <= 1)
{
    strategy->current_was_in_ring = true;
    *buf_state = local_buf_state;
    return buf;
}

/* 源文件：src/backend/storage/buffer/bufmgr.c:2536-2548 */
buf_state = LockBufHdr(bufHdr);

if (BUF_STATE_GET_REFCOUNT(buf_state) == 0 &&
    BUF_STATE_GET_USAGECOUNT(buf_state) == 0)
{
    result |= BUF_REUSABLE;  // 标记为可替换
}
else if (skip_recently_used)
{
    /* Caller told us not to write recently-used buffers */
    UnlockBufHdr(bufHdr, buf_state);
    return result;
}

/* 源文件：src/backend/storage/buffer/bufmgr.c:1735-1737 */

if (pg_atomic_compare_exchange_u32(&buf->state, &old_buf_state,
                                   buf_state))
{
    result = (buf_state & BM_VALID) != 0;
    break;
}

/* 源文件：src/include/storage/buf_internals.h:195-221 */
/*
 * Concurrent access to buffer headers has proven to be more efficient if
 * they're cache line aligned. So we force the start of the BufferDescriptors
 * array to be on a cache line boundary and force the elements to be cache
 * line sized.
 *
 * XXX: As this is primarily matters in highly concurrent workloads which
 * probably all are 64bit these days, and the space wastage would be a bit
 * more noticeable on 32bit systems, we don't force the stride to be cache
 * line sized on those. If somebody does actual performance testing, we can
 * reevaluate.
 *
 * Note that local buffer descriptors aren't forced to be aligned - as there's
 * no concurrent access to those it's unlikely to be beneficial.
 *
 * We use a 64-byte cache line size here, because that's the most common
 * size. Making it bigger would be a waste of memory. Even if running on a
 * platform with either 32 or 128 byte line sizes, it's good to align to
 * boundaries and avoid false sharing.
 */
#define BUFFERDESC_PAD_TO_SIZE  (SIZEOF_VOID_P == 8 ? 64 : 1)

typedef union BufferDescPadded
{
    BufferDesc  bufferdesc;
    char        pad[BUFFERDESC_PAD_TO_SIZE];
} BufferDescPadded;

/* 源文件：contrib/pg_buffercache/pg_buffercache_pages.c:161 */

fctx->record[i].usagecount = BUF_STATE_GET_USAGECOUNT(buf_state);