defmodule SupervisedServer do
@moduledoc """
A behaviour module for starting supervised GenServer processes.
With the use of `SupervisedServer`, you can avoid the need to add `c:start_link/1` function
to your module every time you write a new one.
And if you need your own `c:start_link/1` function, you can override it.
## Usage
* Add `use SupervisedServer` to your module.
* View [`Examples`](#module-examples).
> #### `use SupervisedServer` {: .info}
>
> When you `use SupervisedServer`, the SupervisedServer module will:
> * set `@behaviour SupervisedServer`,
> * add `use GenServer`,
> * pass options passed to `use SupervisedServer` to `use GenServer`,
> * define a `c:start_link/1` function, so your module does not need to define it
> if you don't want a custom one.
## Callbacks
The following callbacks may be implemented by modules that use the `SupervisedServer` behavior:
- `c:start_link/1`: Starts a GenServer process linked to the current process.
This function is often used to start the server as part of a supervision tree.
`c:start_link/1` callback should return one of the following values:
- `{:ok, pid}`: The server was successfully created and initialized.
- `:ignore`: The server should be ignored, and no further action is taken.
- `{:error, {:already_started, pid}}`: A process with the specified name already exists.
- `{:error, reason}`: The initialization of the server failed for the given reason.
- `{:stop, reason}`: The process is terminated due to the provided reason.
## Options
`c:start_link/1` callback accept the following option:
- `:name` (optional): Used for name registration as described in the "Name Registration" section
in the documentation for `GenServer`.
## Examples
### Basic usage
```elixir
iex> defmodule MyServer do
...> use SupervisedServer
...>
...> @impl GenServer
...> def init(arg) do
...> {:ok, arg}
...> end
...>end
...># Starting a supervised process
...>{:ok, _} = Supervisor.start_link([MyServer], strategy: :one_for_one)
```
### Additional options
```elixir
iex> defmodule TransientServer do
...> use SupervisedServer, restart: :transient, shutdown: 10_000
...>
...> @impl GenServer
...> def init(arg) do
...> {:ok, arg}
...> end
...>end
...># Starting a supervised process
...>{:ok, sup} = Supervisor.start_link([TransientServer], strategy: :one_for_one)
...>{:ok, chldspec} = :supervisor.get_childspec(sup, TransientServer)
...>assert chldspec.restart == :transient
...>assert chldspec.shutdown == 10_000
```
### Naming the process
```elixir
iex>defmodule NamedServer do
...> use SupervisedServer
...>
...> @impl GenServer
...> def init(arg) do
...> {:ok, arg}
...> end
...>
...> @impl GenServer
...> def handle_call(:get_my_arg, _from, state) do
...> {:reply, {:ok, state[:my_arg]}, state}
...> end
...>
...> def get_my_arg(pid) do
...> GenServer.call(pid, :get_my_arg)
...> end
...>end
...>
...>children = [
...> {NamedServer, [my_arg: "Hello named server!", name: :my_named_server]}
...>]
...># Starting a named supervised process
...>{:ok, _} = Supervisor.start_link(children, strategy: :one_for_one)
...>
...># Access the named process using its registered name
...>{:ok, "Hello named server!"} = NamedServer.get_my_arg(:my_named_server)
```
### Custom start_link/1
```elixir
iex>defmodule CustomServer do
...> use SupervisedServer
...>
...> # Override start_link/1 to provide additional options
...> @impl SupervisedServer
...> def start_link(args) when is_list(args) do
...> GenServer.start_link(__MODULE__, args, name: :custom_server)
...> end
...>
...> @impl GenServer
...> def init(arg) do
...> {:ok, arg}
...> end
...>end
...>
...># Starting a custom supervised GenServer process
...>{:ok, _} = Supervisor.start_link([CustomServer], strategy: :one_for_one)
...>pid = Process.whereis(:custom_server)
...>true = is_pid(pid)
```
## References
* `GenServer`
* `Supervisor`
"""
@doc """
Starts a `SupervisedServer` process linked to the current process.
This is often used to start the `SupervisedServer` as part of a supervision tree.
Once the server is started, the `init/1` function of the given is called
with `init_arg` as its argument to initialize the server. To ensure a
synchronized start-up procedure, this function does not return until `init/1`
has returned.
Note that a `SupervisedServer` started with `c:start_link/1` is linked to the
parent process and will exit in case of crashes from the parent. The `SupervisedServer`
will also exit due to the `:normal` reasons in case it is configured to trap
exits in the `init/1` callback.
## Options
- `:name` (optional): Used for name registration as described in the "Name Registration" section
in the documentation for `GenServer`.
## Return values
If the server is successfully created and initialized, this function returns
`{:ok, pid}`, where `pid` is the PID of the server. If a process with the
specified server name already exists, this function returns
`{:error, {:already_started, pid}}` with the PID of that process.
If the `init/1` callback fails with `reason`, this function returns
`{:error, reason}`. Otherwise, if it returns `{:stop, reason}`
or `:ignore`, the process is terminated and this function returns
`{:error, reason}` or `:ignore`, respectively.
"""
@callback start_link(args) :: GenServer.on_start()
when args: list
@doc false
@spec __using__(opts :: keyword) :: Macro.t()
defmacro __using__(opts) do
quote location: :keep, bind_quoted: [opts: opts] do
@behaviour SupervisedServer
use GenServer, Macro.escape(opts)
@doc false
@impl SupervisedServer
def start_link(args) when is_list(args) do
{name, init_args} = Keyword.pop(args, :name)
case name do
nil -> GenServer.start_link(__MODULE__, init_args)
_ -> GenServer.start_link(__MODULE__, init_args, name: name)
end
end
defoverridable start_link: 1
end
end
end
