locks and sync

The cluster-wide locking primitives, plus their in-process and OS-level cousins.

internal/dsync

The DRWMutex algorithm. A write-lock requires acknowledgements from a quorum of lock servers; a read-lock requires a smaller quorum. Files of interest:

• dsync.go — top-level DSync state.
• drwmutex.go — the distributed RW mutex implementation.
• Tests prove the algorithm under random peer failures.

It is consumed by cmd/namespace-lock.go and exposed across the cluster via cmd/lock-rest-server.go. The DSync paper-style invariants are enforced inside DRWMutex; consumers just call Lock() / RLock() / Unlock().

internal/lsync

In-process lightweight sync helpers — primarily an LRWMutex that supports a try-lock with timeout semantic. Used by hot-path code that wants to bail out instead of waiting forever.

internal/lock

OS-level filesystem locks (fcntl/flock). Used to protect writes to single-instance state files like format.json, the encrypted config blob, and IAM JSON files.

How they fit together

graph LR
    NS[cmd/namespace-lock.go] --> LL[cmd/local-locker.go]
    NS --> DS[internal/dsync.DRWMutex]
    DS --> LR[lock-rest peer endpoints]
    XL[xl-storage] --> FS[internal/lock fcntl]

• In a single-node deploy. cmd/namespace-lock.go uses only the in-process cmd/local-locker.go.
• In a multi-node deploy. cmd/namespace-lock.go wraps internal/dsync.DRWMutex, which contacts every peer's lock-rest endpoint over internal/rest (or grid).
• For local file writes. Every drive-level write to a singleton file uses internal/lock to ensure only one process has it open.

Integration points

• cmd/namespace-lock.go is the public face for bucket/object operations.
• cmd/format-erasure.go, cmd/iam-object-store.go, cmd/config-current.go use internal/lock for their on-disk state.
• cmd/lock-rest-server.go exposes DSync to the cluster.

Entry points for modification

• DSync algorithm. Tread carefully; the invariants are subtle. Read internal/dsync/dsync.go and the tests.
• New filesystem singleton. Wrap writes with internal/lock; pick the timeout based on how long an operator should wait if a stale lock exists.
• New in-process primitive. Add to internal/lsync; keep the API surface tiny.

See Distributed locking for the runtime view.