This library is designed to provide simple locking mechanisms in Erlang/Elixir, similar to how spinlocks work in other languages - except using messages to communicate locking.

This is useful for libraries which require lock synchronization, without having to roll your own (however simple). Locks can be held by arbitrary numbers of process, making it possible to implement various throttling mechanisms.

Best of all, this library is tiny! It builds upon basic OTP principles to implement lock behaviour via simple processes and message passing.

Follow the instructons found here to configure your Rebar setup to use Hex as a dependency source, then you can grab it directly:

{deps,[
  % pulls the latest version
  sleeplocks,
  % to pull the latest version from github
  {sleeplocks, {git, "git://github.com/whitfin/sleeplocks.git"}}
]}.

To install it for your project, you can pull it directly from Hex. Rather than use the version shown below, you can use the latest version from Hex (shown at the top of this README).

def deps do
  [{:sleeplocks, "~> 1.0"}]
end

Snippets below contain sample usage in both Erlang and Elixir, and cover most of the small API space offered by sleeplocks. For a more complete example, scroll down!

% create a new single lock (with a name)
1> sleeplocks:new(1, [{name, {local, my_lock}}]).
{ok,<0.179.0>}

% take ownership of the lock
2> sleeplocks:acquire(my_lock).
ok

% release the current hold on a lock
3> sleeplocks:release(my_lock).
ok

% attempt to acquire a lock (which will succeed)
4> sleeplocks:attempt(my_lock).
ok

% now that it's taken, other attempts will fail
5> sleeplocks:attempt(my_lock).
{error,unavailable}

% release the lock again
6> sleeplocks:release(my_lock).
ok

% handle acquisition and locking automatically
7> sleeplocks:execute(my_lock, fun() ->
7>   3
7> end).
3

# create a new single lock (with a name)
iex(1)> :sleeplocks.new(1, [ name: :my_lock ])
{:ok, #PID<0.179.0>}

# take ownership of the lock
iex(2)> :sleeplocks.acquire(:my_lock)
:ok

# release the current hold on a lock
iex(3)> :sleeplocks.release(:my_lock)
:ok

# attempt to acquire a lock (which will succeed)
iex(4)> :sleeplocks.attempt(:my_lock)
:ok

# now that it's taken, other attempts will fail
iex(5)> :sleeplocks.attempt(:my_lock)
{:error, :unavailable}

# release the lock again
iex(6)> :sleeplocks.release(:my_lock)
:ok

# handle acquisition and locking automatically
iex(7)> :sleeplocks.execute(:my_lock, fn ->
iex(7)>   3
iex(7)> end)
3

This example is in Elixir, but it should be fairly understandable for those coming from both languages. It simply spawns 6 processes which each attempt to hold a lock for 10 seconds. As the lock is created with only 2 slots, this runs for 30 seconds and 2 of our spawned tasks can hold the lock at any given time.

# First create a new lock, with 2 slots only
{:ok, ref} = :sleeplocks.new(2)

# Then spawn 6 tasks, which each just sleep for 10 seconds
# after acquiring the lock. This means that 2 processes will
# acquire a lock and then release after 10 seconds. This
# will repeat 3 times (6 / 2) until 30 seconds are up.
for idx <- 1..6 do
  Task.start(fn ->
    :sleeplocks.execute(ref, fn ->
      IO.puts("Locked #{idx}")
      Process.sleep(10_000)
      IO.puts("Releasing #{idx}")
    end)
  end)
end