Supervisor.start_link/2 documentation incomplete?

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

It is this type of thing why I would give priority to

[Erlang] Designing for Scalability with Erlang/OTP (O'Reilly)

over

The Little Elixir & OTP Guidebook (Manning)


This goes back to the Erlang documentation:

http://erlang.org/doc/man/supervisor.html#start_link-2

1 Like

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