Adding docs

Author: farhadi

README.md

@@ -41,7 +41,7 @@ the number of requests to acquire the lock, and the other holds the number of re
 This approach offers several advantages over conventional spinlock implementations. Firstly,
 lock acquisition is ordered, meaning locks are acquired in the same sequence they are requested.
 This feature ensures consistent and predictable latency. Secondly, it tracks the number of
-processes concurrently busy-waiting to acquire a lock. By allowing only the initial few processes
+processes concurrently busy-waiting to acquire a lock. By allowing only the next process
 to busy-wait in a tight loop and interrupting spinning for the others with `erlang:yield/0`,
 this method reduces spinlock starvation and offers other processes more opportunities to run.
 

rebar.config

@@ -8,3 +8,13 @@
 {plugins, [covertool]}.
 
 {covertool, [{coverdata_files, ["ct.coverdata"]}]}.
+
+{project_plugins, [rebar3_ex_doc]}.
+
+{hex, [{doc, ex_doc}]}.
+
+{ex_doc, [
+    {source_url, <<"https://github.com/farhadi/spinlock">>},
+    {extras, [<<"README.md">>, <<"LICENSE">>]},
+    {main, <<"readme">>}
+]}.

src/spinlock.app.src

@@ -1,6 +1,6 @@
 {application, spinlock, [
     {description, "Spinlock for Erlang and Elixir"},
-    {vsn, "0.2.0"},
+    {vsn, "0.2.1"},
     {registered, []},
     {applications, [
         kernel,

src/spinlock.erl

@@ -19,11 +19,25 @@
 
 -export_type([spinlock/0]).
 
+%% @equiv new([])
 -spec new() -> #spinlock{}.
 new() ->
     new([]).
 
--spec new([option()]) -> #spinlock{}.
+%% @doc Creates a new spinlock instance with the given options.
+%%
+%% Possible options are:
+%% <ul>
+%% <li>`{max_retry, MaxRetry}'
+%% <p>The lock is forecibly released after `MaxRetry' number of attempts.</p>
+%% </li>
+%% <li>`{atomics_ref, AtomicsRef}'
+%% <p>Uses the first two index of the given atomics array to store the state of the lock.
+%% If you want to use spinlock to implement transactions for an atomics array, you can use this
+%% option to avoid creating an extra atomics array.</p>
+%% </li>
+%% </ul>
+-spec new(Options :: [option()]) -> #spinlock{}.
 new(Options) ->
     MaxRetry = proplists:get_value(max_retry, Options, 100_000),
     is_integer(MaxRetry) andalso MaxRetry > 0 orelse error(badarg),
@@ -37,20 +51,35 @@ new(Options) ->
         max_retry = MaxRetry
     }.
 
--spec acquire(#spinlock{}) -> lock_id().
+%% @doc Acquires a lock for the current process.
+%%
+%% This will busy-wait until a lock can be acquired, or a maximum configured number
+%% of attemps is reached. Returned `lock_id' is used to release the lock later.
+-spec acquire(Lock :: #spinlock{}) -> lock_id().
 acquire(Lock = #spinlock{ref = Ref}) ->
     LockId = atomics:add_get(Ref, 1, 1),
     spin(Lock, LockId - 1, undefined, 0).
 
--spec release(#spinlock{}, lock_id()) -> ok | {error, already_released | invalid_lock_id}.
+%% @doc Releases an already acquired lock.
+%%
+%% This will release the lock for the given LockId.
+%% Returns `ok' if the lock is successfully released. Otherwise returns
+%% `{error, already_released}' if the lock is already released
+%% or `{error, invalid_lock_state}' if the given LockId has never been acquired.
+-spec release(Lock :: #spinlock{}, LockId :: lock_id()) ->
+    ok | {error, already_released | invalid_lock_id}.
 release(#spinlock{ref = Ref}, LockId) ->
     case atomics:compare_exchange(Ref, 2, LockId - 1, LockId) of
         ok -> ok;
         Id when Id >= LockId -> {error, already_released};
         _ -> {error, invalid_lock_id}
     end.
 
--spec transaction(#spinlock{}, fun(() -> any())) -> any().
+%% @doc Executes the given function in a transaction.
+%%
+%% Acquires the lock, executes the given function, and releases the lock when the function has returend.
+%% The lock is released even if the function fails with an exception.
+-spec transaction(Lock :: #spinlock{}, Fun :: fun(() -> any())) -> any().
 transaction(Lock, Fun) ->
     LockId = acquire(Lock),
     try Fun() of
@@ -59,7 +88,11 @@ transaction(Lock, Fun) ->
         release(Lock, LockId)
     end.
 
--spec status(#spinlock{}) ->
+%% @doc Returns the status of the given lock.
+%%
+%% You can use this function for debugging purposes, to check the current status of the lock,
+%% and to see how many process are waiting to acquire the lock.
+-spec status(Lock :: #spinlock{}) ->
     #{released => non_neg_integer(), is_locked => boolean(), waiting => non_neg_integer()}.
 status(#spinlock{ref = Ref}) ->
     Released = atomics:get(Ref, 2),
@@ -70,13 +103,17 @@ status(#spinlock{ref = Ref}) ->
         waiting => max(Total - Released - 1, 0)
     }.
 
+%%%-------------------------------------------------------------------
+%% Internal functions
+%%%-------------------------------------------------------------------
+
 spin(Lock = #spinlock{ref = Ref, max_retry = MaxRetry}, ExpectedId, ReleasedId, MaxRetry) ->
     atomics:compare_exchange(Ref, 2, ReleasedId, ReleasedId + 1),
     spin(Lock, ExpectedId, ReleasedId, 0);
 spin(Lock = #spinlock{ref = Ref}, ExpectedId, LastReleasedId, Retry) ->
     case atomics:get(Ref, 2) of
         LastReleasedId ->
-            LastReleasedId < ExpectedId - 10 andalso erlang:yield(),
+            LastReleasedId < ExpectedId - 1 andalso erlang:yield(),
             spin(Lock, ExpectedId, LastReleasedId, Retry + 1);
         ExpectedId ->
             ExpectedId + 1;

test/spinlock_SUITE.erl

@@ -27,8 +27,8 @@ receive_msg() ->
 all() ->
     [
         new,
-        acquire_and_release,
-        ordered_acquire,
+        lock_status,
+        waiting_status,
         concurrent_acquire,
         acquire_timeout,
         invalid_lock_id,
@@ -45,7 +45,7 @@ new(_Config) ->
     Lock3 = spinlock:new([{atomics_ref, Ref}]),
     ?assertMatch(#spinlock{ref = Ref}, Lock3).
 
-acquire_and_release(_Config) ->
+lock_status(_Config) ->
     Lock = spinlock:new(),
     ?assertEqual(#{is_locked => false, released => 0, waiting => 0}, spinlock:status(Lock)),
     LockId = spinlock:acquire(Lock),
@@ -56,7 +56,7 @@ acquire_and_release(_Config) ->
     ?assertEqual({error, already_released}, spinlock:release(Lock, LockId)),
     ?assertEqual(#{is_locked => false, released => 1, waiting => 0}, spinlock:status(Lock)).
 
-ordered_acquire(_Config) ->
+waiting_status(_Config) ->
     Lock = spinlock:new(),
     LockId = spinlock:acquire(Lock),
     ?assertEqual(1, LockId),