Skip to content

dflockd

A lightweight distributed lock server using a simple line-based TCP protocol with FIFO ordering, automatic lease expiry, and background renewal.

Features

  • Strict FIFO ordering — waiters are granted locks in the order they enqueue, per key
  • Two-phase lock acquisition — split enqueue and wait to notify external systems between joining the queue and blocking
  • Automatic lease expiry — held locks expire if not renewed, preventing deadlocks
  • Disconnect cleanup — locks are released automatically when a client disconnects
  • Zero dependencies — single Go binary
  • Go client library — high-level Lock type with automatic renewal and sharding, plus low-level protocol API
  • Runtime stats — query active connections, held locks, semaphores, and idle entries via the stats command
  • Built-in benchmarking — cmd/bench measures lock throughput and latency under concurrent load
  • Simple wire protocol — line-based UTF-8 over TCP, easy to integrate from any language

Quick example

# Acquire a lock with 10s timeout
printf 'l\nmy-key\n10\n' | nc localhost 6388
# Response: ok <token> <lease_ttl>

# Release (substitute your token)
printf 'r\nmy-key\n<token>\n' | nc localhost 6388
# Response: ok

Getting started

  • Installation — build from source or go install
  • Quick Start — run the server and acquire your first lock
  • Examples — TCP protocol examples and Go client usage
  • Go Client — client package with automatic renewal, sharding, and two-phase locking