NimbleOwnership

https://hexdocs.pm/nimble_ownership/
Admin
NimbleOwnership is an Elixir library that allows managing and tracking ownership of resources across...
Tokens:10,462
Snippets:83
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### start_link(options \\ [])

Source: https://hexdocs.pm/nimble_ownership/index.html

Starts an ownership server.

```APIDOC
## start_link(options \ [])

### Description
Starts an ownership server.

### Parameters
- `options` (list) - Optional - Options for starting the server (default []).

```

--------------------------------

### start_link(options \\ [])

Source: https://hexdocs.pm/nimble_ownership/index.html

Starts an ownership server. This function accepts a keyword list of options and returns a GenServer start result.

```APIDOC
## start_link(options \\ [])

### Description
Starts an ownership server.

### Function Signature
start_link(options \\ [])

### Spec
@spec start_link(keyword()) :: GenServer.on_start()

### Parameters
- **options** (keyword()) - Optional - A keyword list of options. Supports all options supported by GenServer.start_link/3, namely: :name, :timeout, :debug, :spawn_opt, :hibernate_after.

### Returns
- GenServer.on_start() - The result of starting the server.
```

--------------------------------

### fetch_owner/4 usage examples

Source: https://hexdocs.pm/nimble_ownership/index.html

Examples demonstrating how to fetch an owner in shared mode and how it returns an error when no owner is found.

```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.set_mode_to_shared(server, pid)
iex> {:shared_owner, owner_pid} = NimbleOwnership.fetch_owner(server, [self()], :whatever_key)
iex> pid == owner_pid
true

iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.fetch_owner(server, [self()], :whatever_key)
:error
```

--------------------------------

### get_owned/4 example

Source: https://hexdocs.pm/nimble_ownership/index.html

Example showing get_owned/4 returning a map of owned keys and metadata, and returning the default when the PID owns no keys.

```elixir
iex> owner = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, owner, :my_key1, fn _ -> {:ok, 1} end)
iex> NimbleOwnership.get_and_update(server, owner, :my_key2, fn _ -> {:ok, 2} end)
iex> NimbleOwnership.get_owned(server, owner)
%{my_key1: 1, my_key2: 2}
iex> NimbleOwnership.get_owned(server, self(), :default)
:default
```

--------------------------------

### start_link/1

Source: https://hexdocs.pm/nimble_ownership/index.html

Starts a NimbleOwnership server process. This is the entry point for tracking ownership of resources.

```APIDOC
## start_link/1

### Description
Starts a NimbleOwnership server process. This is the entry point for tracking ownership of resources.

### Method
Function call

### Endpoint
start_link(options)

### Parameters
- options (keyword list) - Required - Options for the server, such as mode (private or shared).

### Response
Returns {:ok, pid} on success, or {:error, reason} on failure.
```

--------------------------------

### Initialize ownership of a key

Source: https://hexdocs.pm/nimble_ownership/index.html

Example showing how to initialize ownership of a key using get_and_update.

```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, pid, :my_key, fn current -> {current, 1} end)
{:ok, nil}
```

--------------------------------

### child_spec(init_arg)

Source: https://hexdocs.pm/nimble_ownership/index.html

Returns a specification to start this module under a supervisor.

```APIDOC
## child_spec(init_arg)

### Description
Returns a specification to start this module under a supervisor.

### Parameters
- `init_arg` (term()) - Required - Arguments to pass to the start function.

```

--------------------------------

### Allow access to a key in NimbleOwnership

Source: https://hexdocs.pm/nimble_ownership/index.html

Demonstrates starting an ownership server, updating a key, allowing another process access to that key, and verifying the owner.

```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, self(), :my_key, fn _ -> {:updated, _meta = %{}} end)
{:ok, :updated}
iex> NimbleOwnership.allow(server, self(), pid, :my_key)
:ok
iex> NimbleOwnership.fetch_owner(server, [pid], :my_key)
{:ok, self()}
```

--------------------------------

### Update metadata associated with a key

Source: https://hexdocs.pm/nimble_ownership/index.html

Example showing how to update existing metadata for a key.

```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, pid, :my_key, fn current -> {current, 1} end)
{:ok, nil}
iex> NimbleOwnership.get_and_update(server, pid, :my_key, fn current -> {current, 2} end)
{:ok, 1}
```

--------------------------------

### child_spec(init_arg)

Source: https://hexdocs.pm/nimble_ownership/index.html

Returns a specification to start this module under a supervisor. This is a standard Elixir callback used when integrating the module into a supervision tree.

```APIDOC
## child_spec(init_arg)

### Description
Returns a specification to start this module under a supervisor. See `Supervisor`.

### Method
Function

### Signature
`child_spec(init_arg)`

### Parameters
- `init_arg` (term) - Required - Argument passed to the start function.

### Returns
A supervisor child specification.
```

--------------------------------

### get_owned(ownership_server, owner_pid, default \ nil, timeout \ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Gets all the keys owned by the given owner PID along with their associated metadata. If the owner does not own any keys, the provided default value is returned.

```APIDOC
## get_owned(ownership_server, owner_pid, default \\ nil, timeout \\ 5000)

### Description
Gets all the keys owned by `owner_pid` with all their associated metadata. If `owner_pid` doesn't own any keys, then this function returns `default`.

### Specification
```elixir
@spec get_owned(server(), pid(), default, timeout()) ::
  %{required(key()) => metadata()} | default
when default: term()
```

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The owner PID whose keys are to be retrieved.
- `default` (term()) - Optional - The value returned if the owner owns no keys. Defaults to `nil`.
- `timeout` (timeout()) - Optional - The timeout for the call. Defaults to 5000.

### Return Value
- A map of keys to metadata if the owner owns keys, otherwise the `default` value.

### Examples
```elixir
iex> owner = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, owner, :my_key1, fn _ -> {:ok, 1} end)
iex> NimbleOwnership.get_and_update(server, owner, :my_key2, fn _ -> {:ok, 2} end)
iex> NimbleOwnership.get_owned(server, owner)
%{my_key1: 1, my_key2: 2}
iex> NimbleOwnership.get_owned(server, self(), :default)
:default
```
```

--------------------------------

### fetch_owner(ownership_server, callers, key, timeout \\ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Gets the owner of key through one of the callers.

```APIDOC
## fetch_owner(ownership_server, callers, key, timeout \ 5000)

### Description
Gets the owner of `key` through one of the `callers`.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `callers` (list of pid()) - Required - List of caller PIDs to use for lookup.
- `key` (key()) - Required - The key to look up.
- `timeout` (timeout()) - Optional - Timeout for the call (default 5000).

```

--------------------------------

### get_owned(ownership_server, owner_pid, default \\ nil, timeout \\ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Gets all the keys owned by owner_pid with all their associated metadata.

```APIDOC
## get_owned(ownership_server, owner_pid, default \ nil, timeout \ 5000)

### Description
Gets all the keys owned by `owner_pid` with all their associated metadata.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The PID whose owned keys to retrieve.
- `default` (term()) - Optional - Default value if no keys are owned (default nil).
- `timeout` (timeout()) - Optional - Timeout for the call (default 5000).

```

--------------------------------

### fetch_owner(ownership_server, callers, key, timeout \ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Gets the owner of a key through one of the callers. Returns the owner PID if a caller owns or is allowed access to the key, or the shared owner if the server is in shared mode.

```APIDOC
## fetch_owner(ownership_server, callers, key, timeout \ 5000)

### Description
Gets the owner of `key` through one of the `callers`. If one of the `callers` owns `key` or is allowed access to `key`, then this function returns `{:ok, owner_pid}`. If the ownership server is in **shared mode**, then this function returns `{:shared_owner, shared_owner_pid}` where `shared_owner_pid` is the PID of the shared owner. This is regardless of the `callers`. If none of the callers owns `key` or is allowed access to `key`, then this function returns `{:error, reason}`.

### Method
Function

### Signature
`fetch_owner(ownership_server, callers, key, timeout \ 5000)`

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `callers` ([pid(), ...]) - Required - List of caller PIDs.
- `key` (key()) - Required - The key to look up.
- `timeout` (timeout()) - Optional - Timeout in milliseconds, defaults to 5000.

### Returns
- `{:ok, owner :: pid()}` - If a caller owns or is allowed access to the key.
- `{:shared_owner, shared_owner :: pid()}` - If the server is in shared mode.
- `:error` - If no caller owns or is allowed access to the key.

### Examples
```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.set_mode_to_shared(server, pid)
iex> {:shared_owner, owner_pid} = NimbleOwnership.fetch_owner(server, [self()], :whatever_key)
iex> pid == owner_pid
true

iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.fetch_owner(server, [self()], :whatever_key)
:error
```
```

--------------------------------

### allow(ownership_server, pid_with_access, pid_to_allow, key, timeout \\ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Allows pid_to_allow to use key through pid_with_access on the given ownership_server. Returns :ok on success or a NimbleOwnership.Error struct on failure.

```APIDOC
## allow(ownership_server, pid_with_access, pid_to_allow, key, timeout \\ 5000)

### Description
Allows `pid_to_allow` to use `key` through `pid_with_access` (on the given `ownership_server`).
Use this function when `pid_with_access` is allowed access to `key`, and you want to also allow `pid_to_allow` to use `key`.

### Parameters
- `ownership_server` (pid) - Required - The ownership server process.
- `pid_with_access` (pid) - Required - The PID that already has access to the key.
- `pid_to_allow` (pid or function) - Required - The PID to allow, or a function returning a pid or list of pids.
- `key` (term) - Required - The key to grant access to.
- `timeout` (integer) - Optional - Timeout in milliseconds, default 5000.

### Return Values
- `:ok` - Success.
- `{:error, %NimbleOwnership.Error{}}` - Error, with `:reason` field set to `{:already_allowed, other_owner_pid}` if `pid_to_allow` is already allowed via another owner, or `:cant_allow_in_shared_mode` if the server is in shared mode.

### Behavior
- Allowances are transitive: if `pid_with_access` allows `pid_to_allow`, it is equivalent to the owner of `pid_with_access` allowing `pid_to_allow`.
- If `pid_with_access` terminates, `pid_to_allow` still has access until the owner terminates or removes the allowance.
- Deferred (lazy) allowances: if the process is not yet started, it can be allowed as a function that returns a pid or list of pids.

### Example
```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, self(), :my_key, fn _ -> {:updated, _meta = %{}} end)
{:ok, :updated}
iex> NimbleOwnership.allow(server, self(), pid, :my_key)
:ok
iex> NimbleOwnership.fetch_owner(server, [pid], :my_key)
{:ok, self()}
```
```

--------------------------------

### allow(ownership_server, pid_with_access, pid_to_allow, key, timeout \\ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Allows pid_to_allow to use key through pid_with_access on the given ownership_server.

```APIDOC
## allow(ownership_server, pid_with_access, pid_to_allow, key, timeout \ 5000)

### Description
Allows `pid_to_allow` to use `key` through `pid_with_access` (on the given `ownership_server`).

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `pid_with_access` (pid()) - Required - The PID that has access to the key.
- `pid_to_allow` (pid()) - Required - The PID to grant access to.
- `key` (key()) - Required - The key to grant access to.
- `timeout` (timeout()) - Optional - Timeout for the call (default 5000).

```

--------------------------------

### get_and_update(ownership_server, owner_pid, key, fun, timeout \\ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Accesses key (owned by owner_pid) or initializes the ownership.

```APIDOC
## get_and_update(ownership_server, owner_pid, key, fun, timeout \ 5000)

### Description
Accesses `key` (owned by `owner_pid`) or initializes the ownership.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The PID that owns the key.
- `key` (key()) - Required - The key to access.
- `fun` (function) - Required - Function to update the value.
- `timeout` (timeout()) - Optional - Timeout for the call (default 5000).

```

--------------------------------

### get_and_update(ownership_server, owner_pid, key, fun, timeout \ 5000)

Source: https://hexdocs.pm/nimble_ownership/index.html

Accesses a key owned by owner_pid or initializes the ownership. It can be used to initialize ownership of a key or update the metadata associated with a key. Only the owner PID can update metadata; allowed processes cannot.

```APIDOC
## get_and_update(ownership_server, owner_pid, key, fun, timeout \ 5000)

### Description
Accesses `key` (owned by `owner_pid`) or initializes the ownership. Use this function to initialize the ownership of a key or to update the metadata associated with a key.

### Function Signature
```elixir
@spec get_and_update(server(), pid(), key(), fun, timeout()) ::
  {:ok, get_value} | {:error, NimbleOwnership.Error.t()}
when fun: (nil | metadata() -> {get_value, updated_metadata :: metadata()}),
     get_value: term()
```

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The PID that owns the key.
- `key` (key()) - Required - The key to access or initialize.
- `fun` (fun) - Required - A function that receives the current metadata (or `nil` if not owned) and returns `{get_value, new_meta}`.
- `timeout` (timeout()) - Optional - Defaults to 5000. The timeout for the operation.

### Behavior
- When `owner_pid` doesn't own `key`, the value passed to `fun` will be `nil`. Otherwise, it will be the current metadata associated with `key` under the owner `owner_pid`.
- `fun` must return `{get_value, new_meta}`. `owner_pid` will start owning `key` and `new_meta` will be the metadata associated with that ownership, or, in case `owner_pid` already owned `key`, then the metadata is updated to `new_meta`.
- If successful, returns `{:ok, get_value}` where `get_value` is the value returned by `fun` in its return tuple. Otherwise, returns `{:error, reason}` (see also `NimbleOwnership.Error`).

### Allowed Processes
Processes that are allowed to access `key` under `owner_pid` **cannot update the metadata using this function**. Only the owner PID can update the metadata. If an allowed process attempts to update the metadata under `key`, this function will return `{:error, ...}`. This function only works if `owner_pid` doesn't own `key` and is not allowed to access `key` by any other PID—in that case, it's considered as a new ownership and `fun` receives `nil`.

### Updating Metadata from an Allowed Process
If you don't directly have access to the owner PID, but you want to update the metadata associated with the owner PID and `key` _from an allowed process_, do this instead:
1. Fetch the owner of `key` through `fetch_owner/3`.
2. Call `get_and_update/4` with the owner PID as `owner_pid`, passing in a callback function that returns the new metadata.

### Shared Mode
When the ownership server is set to **shared mode**, you can only call this function with `owner_pid` set to the shared owner PID. See the module documentation.

### Examples
Initializing the ownership of a key:
```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, pid, :my_key, fn current -> {current, 1} end)
{:ok, nil}
```

Updating the metadata associated with a key:
```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> NimbleOwnership.get_and_update(server, pid, :my_key, fn current -> {current, 1} end)
{:ok, nil}
iex> NimbleOwnership.get_and_update(server, pid, :my_key, fn current -> {current, 2} end)
{:ok, 1}
```

Attempting to update the metadata from an allowed process results in an error:
```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> {:ok, _} = NimbleOwnership.get_and_update(server, pid, :some_key, fn _ -> {nil, 1} end)
iex> :ok = NimbleOwnership.allow(server, pid, self(), :some_key)
iex> {:error, error} = NimbleOwnership.get_and_update(server, self(), :some_key, fn current -> {current, 2} end)
iex> %NimbleOwnership.Error{} = error
iex> {:already_allowed, ^pid} = error.reason
iex> error.key
:some_key
```
```

--------------------------------

### Define server() type

Source: https://hexdocs.pm/nimble_ownership/index.html

Defines the server() type as a GenServer.server().

```elixir
@type server() :: GenServer.server()
```

--------------------------------

### set_owner_to_manual_cleanup(ownership_server, owner_pid)

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets the owner PID to manual cleanup mode. This function can be called before any keys are owned and returns :ok upon success.

```APIDOC
## set_owner_to_manual_cleanup(ownership_server, owner_pid)

### Description
Sets the owner PID to manual cleanup mode. If `owner_pid` doesn't own any keys, this function still sets its cleanup mode to manual. This means you can call this before any calls to `get_and_update/4` and it will still work as expected.

### Specification
```elixir
@spec set_owner_to_manual_cleanup(server(), pid()) :: :ok
```

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The owner PID to set to manual cleanup mode.

### Return Value
- `:ok`

### Notes
- If you set an owner PID to manual cleanup mode and you don't call `cleanup_owner/2` before the owner PID goes down, then you will have a leak. This is because the ownership server will not clean up the allowances and owned keys associated with the owner PID when said PID goes down. See the _Cleanup_ section in the module documentation.
```

--------------------------------

### set_mode_to_shared(ownership_server, shared_owner)

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets the ownership server to shared mode and sets shared_owner as the shared owner.

```APIDOC
## set_mode_to_shared(ownership_server, shared_owner)

### Description
Sets the ownership server to _shared mode_ and sets `shared_owner` as the shared owner.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `shared_owner` (pid()) - Required - The PID to set as the shared owner.

```

--------------------------------

### set_owner_to_manual_cleanup(ownership_server, owner_pid)

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets the owner PID to manual cleanup mode.

```APIDOC
## set_owner_to_manual_cleanup(ownership_server, owner_pid)

### Description
Sets the owner PID to manual cleanup mode.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The PID to set to manual cleanup mode.

```

--------------------------------

### allow/4

Source: https://hexdocs.pm/nimble_ownership/index.html

Allows a process access to a key through the owner PID or PIDs already allowed to access the key. This is used to grant access to resources.

```APIDOC
## allow/4

### Description
Allows a process access to a key through the owner PID or PIDs already allowed to access the key. This is used to grant access to resources.

### Method
Function call

### Endpoint
allow(server, key, pid, metadata)

### Parameters
- server (pid) - Required - The NimbleOwnership server process.
- key (term) - Required - The key to allow access to.
- pid (pid) - Required - The process to allow access.
- metadata (metadata/0) - Required - Arbitrary metadata to store alongside the owned resource.

### Response
Returns :ok on success.
```

--------------------------------

### Error when updating from an allowed process

Source: https://hexdocs.pm/nimble_ownership/index.html

Demonstrates that an allowed process cannot update metadata using get_and_update.

```elixir
iex> pid = spawn(fn -> Process.sleep(:infinity) end)
iex> {:ok, server} = NimbleOwnership.start_link()
iex> {:ok, _} = NimbleOwnership.get_and_update(server, pid, :some_key, fn _ -> {nil, 1} end)
iex> :ok = NimbleOwnership.allow(server, pid, self(), :some_key)
iex> {:error, error} = NimbleOwnership.get_and_update(server, self(), :some_key, fn current -> {current, 2} end)
iex> %NimbleOwnership.Error{} = error
iex> {:already_allowed, ^pid} = error.reason
iex> error.key
:some_key
```

--------------------------------

### set_mode_to_shared(ownership_server, shared_owner)

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets the ownership server to shared mode and designates the given PID as the shared owner. This function returns :ok upon success.

```APIDOC
## set_mode_to_shared(ownership_server, shared_owner)

### Description
Sets the ownership server to _shared mode_ and sets `shared_owner` as the shared owner. See the module documentation for more information.

### Specification
```elixir
@spec set_mode_to_shared(server(), pid()) :: :ok
```

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `shared_owner` (pid()) - Required - The PID to set as the shared owner.

### Return Value
- `:ok`
```

--------------------------------

### cleanup_owner(ownership_server, owner_pid)

Source: https://hexdocs.pm/nimble_ownership/index.html

Manually cleans up allowances and owned keys associated with the given owner PID. This is meant to be used in conjunction with `set_owner_to_manual_cleanup/2`.

```APIDOC
## cleanup_owner(ownership_server, owner_pid)

### Description
Manually cleans up allowances and owned keys associated with `owner_pid`. This is meant to be used in conjunction with `set_owner_to_manual_cleanup/2`.

### Method
Function

### Signature
`cleanup_owner(ownership_server, owner_pid)`

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The PID of the owner to clean up.

### Returns
`:ok`
```

--------------------------------

### set_owner_to_manual_cleanup/2 spec

Source: https://hexdocs.pm/nimble_ownership/index.html

Specification for set_owner_to_manual_cleanup/2, which sets an owner PID to manual cleanup mode. It works even if the PID owns no keys, but can cause leaks if cleanup_owner/2 is not called before the PID exits.

```elixir
@spec set_owner_to_manual_cleanup(server(), pid()) :: :ok
```

--------------------------------

### set_mode_to_private(ownership_server)

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets the ownership server to private mode. This function returns :ok upon success.

```APIDOC
## set_mode_to_private(ownership_server)

### Description
Sets the ownership server to _private mode_. See the module documentation for more information.

### Specification
```elixir
@spec set_mode_to_private(server()) :: :ok
```

### Parameters
- `ownership_server` (server()) - Required - The ownership server.

### Return Value
- `:ok`
```

--------------------------------

### cleanup_owner(ownership_server, owner_pid)

Source: https://hexdocs.pm/nimble_ownership/index.html

Manually cleans up allowances and owned keys associated with owner_pid.

```APIDOC
## cleanup_owner(ownership_server, owner_pid)

### Description
Manually cleans up allowances and owned keys associated with `owner_pid`.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.
- `owner_pid` (pid()) - Required - The PID whose allowances and owned keys should be cleaned up.

```

--------------------------------

### cleanup_owner/2

Source: https://hexdocs.pm/nimble_ownership/index.html

Manually cleans up the allowances and owned keys associated with an owner PID.

```APIDOC
## cleanup_owner/2

### Description
Manually cleans up the allowances and owned keys associated with an owner PID.

### Method
Function call

### Endpoint
cleanup_owner(server, owner_pid)

### Parameters
- server (pid) - Required - The NimbleOwnership server process.
- owner_pid (pid) - Required - The owner PID to clean up.

### Response
Returns :ok on success.
```

--------------------------------

### fetch_owner/3

Source: https://hexdocs.pm/nimble_ownership/index.html

Checks if a PID can access the given key and returns the owner PID and metadata.

```APIDOC
## fetch_owner/3

### Description
Checks if a PID can access the given key and returns the owner PID and metadata.

### Method
Function call

### Endpoint
fetch_owner(server, key, pid)

### Parameters
- server (pid) - Required - The NimbleOwnership server process.
- key (term) - Required - The key to check access for.
- pid (pid) - Required - The process to check access for.

### Response
Returns {:ok, {owner_pid, metadata}} if the PID can access the key, or :error otherwise.
```

--------------------------------

### Define key() type

Source: https://hexdocs.pm/nimble_ownership/index.html

Defines the key() type as an arbitrary term.

```elixir
@type key() :: term()
```

--------------------------------

### set_owner_to_manual_cleanup/2

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets an owner PID to manual cleanup mode, so that allowances and owned keys are not automatically cleaned up when the owner terminates.

```APIDOC
## set_owner_to_manual_cleanup/2

### Description
Sets an owner PID to manual cleanup mode, so that allowances and owned keys are not automatically cleaned up when the owner terminates.

### Method
Function call

### Endpoint
set_owner_to_manual_cleanup(server, owner_pid)

### Parameters
- server (pid) - Required - The NimbleOwnership server process.
- owner_pid (pid) - Required - The owner PID to set to manual cleanup mode.

### Response
Returns :ok on success.
```

--------------------------------

### set_mode_to_private(ownership_server)

Source: https://hexdocs.pm/nimble_ownership/index.html

Sets the ownership server to private mode.

```APIDOC
## set_mode_to_private(ownership_server)

### Description
Sets the ownership server to _private mode_.

### Parameters
- `ownership_server` (server()) - Required - The ownership server.

```

--------------------------------

### get_and_update/5 specification

Source: https://hexdocs.pm/nimble_ownership/index.html

The type specification for the get_and_update function.

```elixir
@spec get_and_update(server(), pid(), key(), fun, timeout()) ::
  {:ok, get_value} | {:error, NimbleOwnership.Error.t()}
when fun: (nil | metadata() -> {get_value, updated_metadata :: metadata()}),
     get_value: term()
```

--------------------------------

### child_spec/1

Source: https://hexdocs.pm/nimble_ownership/index.html

Returns a child specification for the NimbleOwnership server, suitable for use in supervision trees.

```APIDOC
## child_spec/1

### Description
Returns a child specification for the NimbleOwnership server, suitable for use in supervision trees.

### Method
Function call

### Endpoint
child_spec(options)

### Parameters
- options (keyword list) - Required - Options for the server, such as mode (private or shared).

### Response
Returns a child specification map.
```

--------------------------------

### Define metadata() type

Source: https://hexdocs.pm/nimble_ownership/index.html

Defines the metadata() type as an arbitrary term associated with an owned key.

```elixir
@type metadata() :: term()
```

--------------------------------

### set_mode_to_shared/2 spec

Source: https://hexdocs.pm/nimble_ownership/index.html

Specification for set_mode_to_shared/2, which sets the ownership server to shared mode with the given shared owner.

```elixir
@spec set_mode_to_shared(server(), pid()) :: :ok
```

--------------------------------

### NimbleOwnership.Error t() type definition

Source: https://hexdocs.pm/nimble_ownership/NimbleOwnership.Error.html

Defines the structure of the NimbleOwnership.Error exception, including the key and various possible error reasons.

```elixir
@type t() :: %NimbleOwnership.Error{
  __exception__: true,
  key: NimbleOwnership.key(),
  reason:
    {:already_allowed, pid()}
    | :not_allowed
    | :already_an_owner
    | :cant_allow_in_shared_mode
    | {:not_shared_owner, pid()}
}
```

--------------------------------

### NimbleOwnership.Error.t()

Source: https://hexdocs.pm/nimble_ownership/NimbleOwnership.Error.html

Type specification for the NimbleOwnership.Error exception struct. It defines the structure of the error returned by NimbleOwnership functions, including the key and reason fields.

```APIDOC
## NimbleOwnership.Error.t()

### Description
Type specification for the NimbleOwnership.Error exception struct. It defines the structure of the error returned by NimbleOwnership functions.

### Type
```elixir
@type t() :: %NimbleOwnership.Error{
  __exception__: true,
  key: NimbleOwnership.key(),
  reason:
    {:already_allowed, pid()}
    | :not_allowed
    | :already_an_owner
    | :cant_allow_in_shared_mode
    | {:not_shared_owner, pid()}
}
```

### Fields
- **__exception__** (boolean) - Always true, indicating this is an exception struct.
- **key** (NimbleOwnership.key()) - The key associated with the error.
- **reason** (tuple or atom) - The reason for the error. Possible values:
  - `{:already_allowed, pid()}` - The process is already allowed.
  - `:not_allowed` - The process is not allowed.
  - `:already_an_owner` - The process is already an owner.
  - `:cant_allow_in_shared_mode` - Cannot allow in shared mode.
  - `{:not_shared_owner, pid()}` - The process is not a shared owner.
```

--------------------------------

### cleanup_owner/2 specification

Source: https://hexdocs.pm/nimble_ownership/index.html

Type specification for the cleanup_owner function, which cleans up allowances and owned keys associated with a specific owner PID.

```elixir
@spec cleanup_owner(server(), pid()) :: :ok
```

--------------------------------

### get_owned/4 spec

Source: https://hexdocs.pm/nimble_ownership/index.html

Specification for get_owned/4, which returns a map of keys to metadata or the default value when the owner PID owns no keys.

```elixir
@spec get_owned(server(), pid(), default, timeout()) ::
  %{required(key()) => metadata()} | default
when default: term()
```

--------------------------------

### set_mode_to_private/1 spec

Source: https://hexdocs.pm/nimble_ownership/index.html

Specification for set_mode_to_private/1, which sets the ownership server to private mode.

```elixir
@spec set_mode_to_private(server()) :: :ok
```

--------------------------------

### fetch_owner/4 specification

Source: https://hexdocs.pm/nimble_ownership/index.html

Type specification for the fetch_owner function, which retrieves the owner of a key based on a list of callers.

```elixir
@spec fetch_owner(server(), [pid(), ...], key(), timeout()) ::
  {:ok, owner :: pid()} | {:shared_owner, shared_owner :: pid()} | :error
```
Tokens:
Raw