A snippet to acquire a Lightweight lock

1. Overview

Recently, I was working on an internal issue related with buffer manager in PostgreSQL, and I saw a typical use of the Lightweight lock in buffer manager like below.

1   INIT_BUFFERTAG(newTag, smgr_rnode.node, forkNum, blockNum);
2   newHash = BufTableHashCode(&newTag);
3   newPartitionLock = BufMappingPartitionLock(newHash);
4   LWLockAcquire(newPartitionLock, LW_SHARED);
5   buf_id = BufTableLookup(&newTag, newHash);
6   LWLockRelease(newPartitionLock);

Basically, when the buffer manger needs to access a buffer block using buffer tag, it will have to acquire a lightweight lock in either shared or exclusive mode, then find the buffer block and then release the lightweight lock.

Since the buffer manager is shared among multiple backends and a buffer block is accessed very often, this snippet has to be designed to protect the data consistency for read and write and no impact on performance.

This blog will explain how this snippet works in PostgreSQL and emphasize a little bit more on the lightweight lock acquire.

2. how to use snapshot public functions

Now, let’s go through the snippet above line by line.
The first line simply uses a Macro to initialize a buffer tag using those five numbers. Here, INIT_BUFFERTAG is a macro defines like below,

#define INIT_BUFFERTAG(a,xx_rnode,xx_forkNum,xx_blockNum) \
( \
    (a).rnode = (xx_rnode), \
    (a).forkNum = (xx_forkNum), \
    (a).blockNum = (xx_blockNum) \
)

After the macro call, the newTag has been assigned with those five numbers, i.e., table space number, database number, relation number, fork number (data, fsm or visibility map etc), and the block number (each block is 8k) within the actual file;

The second line newHash = BufTableHashCode(&newTag); generates a hash number based on the buffer tag. Where, The function BufTableHashCode computes the hash code associated with given buffer tag in the global shared buffer hash table, and return a unsigned integer.

The third line retrieves a partition lock within the locks pool used an unsigned integer hash number mod the total number of partition locks (default 128).
Again, the function BufMappingPartitionLock is a predefined macro and is showing below.

#define BufMappingPartitionLock(hashcode) \
    (&MainLWLockArray[BUFFER_MAPPING_LWLOCK_OFFSET + \
        BufTableHashPartition(hashcode)].lock)

It will return a lock in MainLWLockArray lightweight locks array. Where the BUFFER_MAPPING_LWLOCK_OFFSET is number of dedicated lightweight locks defined in lwlocknames.txt file. The number of partition lightweight locks are 128 locks located after these dedicated locks defined in these main lightweight locks array. Here, the macro BufTableHashPartition is to make sure it always returns a lock in the partition locks pool for any given hash number.

The fourth line to is to acquire the lightweight lock with a very efficient algorithm. This LWLockAcquire will help return a lightweight lock in the specified mode, i.e., shared (for read only operation) or exclusive (for write operation). This function returns true if the lock was available immediately, false if it has to sleep and wait.
Inside this LWLockAcquire, there are many considerations, but I want to emphasize one smart c implementation in the function LWLockAttemptLock, and I believe you can use this similar idea as a design pattern to design other CPU and Memory sensitive logic in your applications.
As you can see below is the key implementation of this shared and exclusive lock.

if (mode == LW_EXCLUSIVE)
{
    lock_free = (old_state & LW_LOCK_MASK) == 0;
    if (lock_free)
        desired_state += LW_VAL_EXCLUSIVE;
}
else
{
    lock_free = (old_state & LW_VAL_EXCLUSIVE) == 0;
    if (lock_free)
        desired_state += LW_VAL_SHARED;
}

This implementation involves three macros: LW_LOCK_MASK, LW_VAL_EXCLUSIVE and LW_VAL_SHARED, where LW_LOCK_MASK is a consistent number, i.e., 0xFFFFFF, used in bit operation. If any lower 24 bits has a one, then it means the lock is held in either shared or exclusive mode. In other words, someone is still reading the data, if you want the update the data, please wait. If the all lower 24 bits are zeros, then it will be assigned to a big number LW_VAL_EXCLUSIVE, i.e., 0x800000, which indicates the lock is used as exclusive. If you want to acquire this lock in shared mode, then as long as the lock is not held by someone in exclusive mode and it is not held more than 0x7FFFFF, then you can acquire one shared lock and the number of usages will be simple increase by one, i.e., LW_VAL_SHARED. Of course, how many shared locks can be held at the same time is limited by other parameters.

Here is the definition of these three macros.

#define LW_LOCK_MASK                ((uint32) ((1 << 25)-1))
#define LW_VAL_EXCLUSIVE            ((uint32) 1 << 24)
#define LW_VAL_SHARED               1

The fifth line looks up the buffer id using the given buffer tag and hash code.
Once you have acquired the lock, work on the operations immediately depends on your application, but keep in mind the lightweight lock is designed to be held only in a short period.

The sixth line release the lock back to the partition lock pool.
After you finished your operations either read or write, then use this LWLockRelease function to release the lock as soon as you can, so you don’t block other processes too long especially if there is a write operation need to acquire this lock in exclusive mode.

3. Summary

In this blog, we discussed a typical snippet which uses a lightweight lock in PostgreSQL, and explained one of the most efficient piece of code implemented for Lightweight lock in PostgreSQL, i.e., LWLockAcquire. I hope this can help when you want to achieve a similar result in your own design.