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 3686 15

2019-02-28 12:13:41 UTC

Showing Posts 15 to 6

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

sasajuric

Author of Elixir In Action

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.

Post #15

peerreynders

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:

Args is any term that is passed as the argument to Module:init/1.

If the supervisor and its child processes are successfully created (that is, if all child process start functions return {ok,Child}, {ok,Child,Info}, or ignore), the function returns {ok,Pid}, where Pid is the pid of the supervisor.

If there already exists a process with the specified SupName, the function returns {error,{already_started,Pid}}, where Pid is the pid of that process.

If Module:init/1 returns ignore, this function returns ignore as well, and the supervisor terminates with reason normal.

If Module:init/1 fails or returns an incorrect value, this function returns {error,Term}, where Term is a term with information about the error, and the supervisor terminates with reason Term.

If any child process start function fails or returns an error tuple or an erroneous value, the supervisor first terminates all already started child processes with reason shutdown and then terminate itself and returns{error, {shutdown, Reason}}.

Post #14

LostKobrakai

It surely can if at least for the Supervisor.start_link/3 version, but skipping the optional options, which are the 3rd parameter.

Post #13

sasajuric

Author of Elixir In Action

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.

Post #12

LostKobrakai

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.

Post #11

Fl4m3Ph03n1x

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!

Post #10

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