GlobalSemaphore

Cluster-wide semaphore with a dead-simple API.

# config :global_semaphore, :limits, pdf_api: 3

GlobalSemaphore.with_permit(:pdf_api, fn ->
  generate_pdf()  # max 3 concurrent calls across the entire cluster
end)

# With priority (lower number = higher priority, default 5)
GlobalSemaphore.with_permit({:pdf_api, 1}, fn ->
  generate_pdf()  # high priority, preempts normal/low requests in the queue
end)

Why?

• Cluster-wide: Works across all nodes, not just one
• Simple: One config line, one function call. No complex concepts.
• No dependencies: Uses Erlang's built-in :global module

Installation

def deps do
  [{:global_semaphore, "~> 0.2.0"}]
end

Usage

# config/runtime.exs
config :global_semaphore, :limits,
  pdf_api: 3,
  email_api: 5

# Recommended: automatic acquire/release
GlobalSemaphore.with_permit(:pdf_api, fn ->
  call_pdf_api()
end)

# With priority (lower number = higher priority, default 5)
GlobalSemaphore.with_permit({:pdf_api, 1}, fn -> call_pdf_api() end)   # high
GlobalSemaphore.with_permit({:pdf_api, 5}, fn -> call_pdf_api() end)   # normal (default)
GlobalSemaphore.with_permit({:pdf_api, 10}, fn -> call_pdf_api() end)  # low

# Manual control when needed
GlobalSemaphore.acquire(:pdf_api)
GlobalSemaphore.acquire({:pdf_api, 1})
try do
  call_pdf_api()
after
  GlobalSemaphore.release(:pdf_api)
end

Limitations

• Uses :global which has known issues during network partitions (rare in practice)
• If the node hosting the semaphore dies, queued requests fail (next request auto-recovers)

License

MIT