Background
I am trying to build an OTP compliant app using supervisors. However I am having trouble interpreting a part of the documentation.
Docs
The documentation states that Supervisor.start_link/2
returns the following:
{:ok, pid}
| :ignore
| {:error, {:already_started, pid} | {:shutdown,term} | [term]}
Problem
The problem is that even though the documentation specifies when start_link
returns {:ok, pid}
and {:error, any}
it doesn’t specify when it returns :ignore
, leaving me to think that it can never return :ignore
.
Question
In which cases does Supervisor.start_link/2
return :ignore
?
If I understand it correctly in module-based supervisors.
Yes, but those use Supervisor.start_link/3
and Supervisor.init/2
. In short, they don’t use Supervisor.start_link/2
.
https://hexdocs.pm/elixir/Supervisor.html#c:init/1
If init/1
returns :ignore
then start_link will return :ignore
. This is useful if you want to selectively start certain parts of your supervision tree / workers.
It’s explicitly documented here https://hexdocs.pm/elixir/GenServer.html#c:init/1
1 Like
The init/1
callback is allowed to return {:ok, {:supervisor.sup_flags(), [:supervisor.child_spec()]}} | :ignore
[Erlang] Designing for Scalability with Erlang/OTP (O'Reilly) p.81:
If the startup fails but you do not want to affect other processes started by the same supervisor, return ignore
.
p.178
The init/1
callback function normally returns the whole tuple comprising the restart tuple and a list of child specifications. But if it instead returns ignore
, the supervisor terminates with reason normal
.
1 Like
Yes, but how is any of this related to Supervisor.start_link/2
?
I don’t care what the children may or may not return. It is specified how the Supervisor.start_link/2
function behaves for those scenarios.
What I really want to know is when Supervisor.start_link/2
returns :ignore
.
In what circumstances?
A supervisor has an init/1
callback as well as workers have. So both actually work the same in regards to returning :ignore
from that callback.
1 Like
Forgive me for my ignorance, but I still don’t see how any of this affects the return value of Supervisor.start_link/2
If a child returns an error, the supervisor returns one.
If a child returns :ok or :ignore, the supervisor returns :ok.
So … when really?
A supervisor can be a child of a supervisor.
When the supervisor itself (it’s init/1
) returns :ignore
then Supervisor.start_link
returns :ignore
.
E.g.
defmodule MyApp.Supervisor do
# Automatically defines child_spec/1
use Supervisor
def start_link(init_arg) do
Supervisor.start_link(__MODULE__, init_arg, name: __MODULE__)
end
@impl true
def init(_init_arg) do
:ignore
end
end
Supervisor.start_link(MyApp.Supervisor, [])
# :ignore
2 Likes
Excellent example!
But where is that code is the usage of Supervisor.start_link/2
?
EDIT: ignore me, I get it now.
Thanks for the help!
In my opinion it doesn’t really belong to start_link
. It’s a behaviour for the init/1
callback, as you can see in the GenServer module, where it’s even mentioned in the documentation text.
I believe you actually got it right initially. It seems that Supervisor.start_link/2
can’t return :ignore
(unless I’m missing some nuance, since I didn’t bother to read the code of Supervisor
). Even the docs for start_link/2
don’t mention it.
You can consider making a PR which would tighten the specification for start_link/2
.
1 Like
It surely can if at least for the Supervisor.start_link/3
version, but skipping the optional options, which are the 3rd parameter.
3 Likes
Ah, good point! I forgot about the optional options thing for start_link/3
. Yeah, in that case, :ignore
is indeed a valid return value.
1 Like