rwlock

redis-rwlock

Distributed RW-lock for Go backed by Redis. Readers acquire the lock shared; a writer acquires it exclusively.

Inspired by the Redis distributed locking pattern. All lock operations are single atomic Lua scripts.

Installation

module github.com/e-chip/redis-rwlock

go 1.24.0

Core package (no Redis dependency):

go get github.com/e-chip/redis-rwlock/pkg/rwlock

Pick an adapter for your Redis client:

# go-redis v9 (current)
go get github.com/e-chip/redis-rwlock/adapters/goredis9
# go-redis v6 (legacy)
go get github.com/e-chip/redis-rwlock/adapters/goredisv6

Usage

import (
    "github.com/e-chip/redis-rwlock/pkg/rwlock"
    goredis9 "github.com/e-chip/redis-rwlock/adapters/goredis9"
    goredis "github.com/redis/go-redis/v9"
)

client := goredis.NewClient(&goredis.Options{Addr: "localhost:6379"})

locker := rwlock.New(
    goredis9.New(client),
    "myapp:lock",          // global lock key
    "myapp:readers",       // reader reference counter key
    "myapp:writer_intent", // writer intent key
    rwlock.Options{},
)

// Shared read access — multiple readers run concurrently.
err := locker.Read(func() {
    // critical section
})

// Exclusive write access — no readers or other writers run concurrently.
err = locker.Write(func() {
    // critical section
})

Custom Redis client

Implement the two-method RedisClient interface to use any Redis client:

type RedisClient interface {
    Ping(ctx context.Context) error
    Eval(ctx context.Context, script string, keys []string, args ...interface{}) (int64, error)
}

Options

Mutex modes

ModePreferWriter — writer-preferring (default). When a writer is waiting, it sets an intent key. New readers detect the intent and back off, letting the writer proceed as soon as existing readers finish. Prevents writer starvation.

ModePreferReader — reader-preferring. The intent key is still set by the writer but readers ignore it. A writer must wait until all readers (present and future) release the lock naturally. May starve writers under continuous read load.

Error reference

Lua scripts

All lock operations are single atomic Lua scripts embedded in the binary (pkg/rwlock/lua/). The reference sources with comments live in lua/.