Supervisor.start_link/2 documentation incomplete?

Fl4m3Ph03n1x

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?

15 comments

#supervisor #documentation #ex_doc

0 3687 15

2019-02-28 12:13:41 UTC

Showing Posts 1 to 10

Show Best Posts
Show All (oldest first)
Show All (newest first)

peerreynders

If I understand it correctly in module-based supervisors.

Post #1

Fl4m3Ph03n1x

Yes, but those use Supervisor.start_link/3 and Supervisor.init/2. In short, they don’t use Supervisor.start_link/2.

Post #2

LostKobrakai

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 GenServer — Elixir v1.20.2

Post #3

peerreynders

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.

Post #4

Fl4m3Ph03n1x

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?

Post #5

LostKobrakai

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.

Post #6

Fl4m3Ph03n1x

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?

Post #7

peerreynders

A supervisor can be a child of a supervisor.

Post #8

LostKobrakai

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

Post #9