# EtsLock
EtsLock is an Elixir library for acquiring exclusive locks on data in
[ETS](http://erlang.org/doc/man/ets.html) tables.
Using `with_ets_lock/4`, you can process all `{key, value}` tuples for a
given `key` while being sure other processes using `with_ets_lock/4`
are not mutating the data stored for this key.
Processing is performed in a separate process so that an execution
timeout (`:exec_timeout`) can be enforced.
For high concurrent performance, all locks are stored in a separate
ETS table, and no GenServers or other processes are used to coordinate
access. This is in contrast to the
(erlang-ets-lock library)[https://github.com/afiskon/erlang-ets-lock/],
which uses a single GenServer to serialize access to ETS.
## Docs
Full documentation is available on
(Hexdocs.pm)[https://hexdocs.pm/ets_lock/EtsLock.html].
## Example usage
iex> table = :ets.new(:whatever, [:set, :public])
iex> spawn(fn ->
...> ## Wait 50ms, try to acquire lock, then insert
...> Process.sleep(50)
...> EtsLock.with_ets_lock(table, :key, fn _ ->
...> :ets.insert(table, {:key, :yup})
...> end)
...> end)
iex> spawn(fn ->
...> ## Acquire lock immediately, hold it for 100ms, then insert
...> EtsLock.with_ets_lock(table, :key, fn _ ->
...> Process.sleep(100)
...> :ets.insert(table, {:key, :nope})
...> end)
...> end)
iex> Process.sleep(200)
iex> :ets.lookup(table, :key)
[{:key, :yup}]
## Options
* `:wait_timeout` - Milliseconds to wait when acquiring a lock.
Default 5000. Set to `:infinity` to try forever to acquire a lock.
* `:exec_timeout` - Milliseconds to allow `fun` to hold the lock before
its execution is cancelled and the lock is released. Default 5000.
Set to `:infinity` to hold the lock indefinitely until `fun` has finished.
* `:fail_timeout` - Milliseconds to wait before forcibly deleting a
lock after it _should_ have been released, but wasn't. Default 1000.
Provides protection against permanently hanging locks in the case that
both the caller and the spawned task crash. Set to `:infinity` to
disable this protection (not recommended).
* `:spin_delay` - Milliseconds to wait between every attempt to acquire a
lock. Default 2.
* `:lock_table` - ETS table in which to store locks. Default `EtsLock.Locks`.
## Installation
Add `ets_lock` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:ets_lock, "~> 0.2.0"}
]
end
```
## Authorship and License
EtsLock is copyright 2019, Appcues, Inc.
EtsLock is released under the MIT License, available at
[LICENSE.txt](LICENSE.txt).