I improved the docs to say:

The Supervisor module was designed to handle mostly static children
that are started in the given order when the supervisor starts. A
DynamicSupervisor starts with no children. Instead, children are
started on demand via start_child/2 and there is no ordering between
children. This allows the DynamicSupervisor to hold millions of
children by using efficient data structures and to execute certain
options, such as shutting down, concurrently.

Permanent == started on app startup and staying there until the app shuts down.

Thanks to this distinction, DynamicSupervisor allows you to start and stop children processes at any time. You also are not strictly mandated to stop them; they will be stopped when the supervisor itself is stopped (although it’s definitely a good idea to stop children proactively after they’ve done their job IMO).

To me, using DynamicSupervisor is appropriate in two scenarios:

1. When you would like to spawn quite a lot of (say, at least 200,000+) processes because I’d wager then a performance (or memory) impact would start becoming noticeable.
2. When you need to create processes in response to – or because of the specifics of – external systems whose resources you have to monitor e.g. a web crawling service to which you give a new domain to crawl. It would need to spawn processes to enumerate URLs and then maintain a small pool of workers to do the crawling (and apply rate limits if applicable).

I’d say especially the latter option is pretty valid; there are many real-world examples where you cannot neatly plan a supervision from the start because things do change at runtime. DynamicSupervisor is ideal for this.

I think the DynamicSupervisor is only a special case of Supervisor that handle only dynamic children. In Erlang there is only supervisor. It is a good habit to separate the static children and the dynamic children in different branches of the supervision tree.

The way that codebase is using Supervisor.start_child/2

  def init(_args) do
    children = [
      World.Location
    ]

    Supervisor.init(children, strategy: :simple_one_for_one)
  end

  def start_child(opts) do
    Supervisor.start_child(__MODULE__, [opts])
  end

is deprecated

  def start_child(supervisor, args) when is_list(args) do
    IO.warn_once(
      {__MODULE__, :start_child},
      "Supervisor.start_child/2 with a list of args is deprecated, please use DynamicSupervisor instead",
      _stacktrace_drop_levels = 2
    )

    call(supervisor, {:start_child, args})
  end

  # in def init/2
        :simple_one_for_one ->
          IO.warn(
            ":simple_one_for_one strategy is deprecated, please use DynamicSupervisor instead"
          )

Migrating from Supervisor’s :simple_one_for_one

I think if you have a supervisor with “regular” strategy, e.g. :one_for_one, and start processes with Supervisor.start_child/2 it’s assumed they’ll be permanent. DynamicSupervisor should be used for dynamic start/termination of arbitrary children.

Supervisor.child_spec/2 is a unique function which receives any child spec (Module, {Module, arg}, or map) and a list of overrides, and returns that child spec with the overrides applied. DynamicSupervisor.child_spec/1 returns a child spec to start a DynamicSupervisor under a supervisor, the same way Registry.child_spec/1 returns a child spec to start a Registry under a supervisor.

iex> DynamicSupervisor.child_spec(name: MyApp.DynamicSupervisor)
%{
  id: MyApp.DynamicSupervisor,
  start: {DynamicSupervisor, :start_link, [[name: MyApp.DynamicSupervisor]]},
  type: :supervisor
}
iex> |> Supervisor.child_spec(id: OverriddenID, shutdown: 10_000)
%{
  id: OverriddenID,
  shutdown: 10000,
  start: {DynamicSupervisor, :start_link, [[name: MyApp.DynamicSupervisor]]},
  type: :supervisor
}

IMO the documentation seems clear about it, but I could see how it would be confusing that they’re both supervisors and DyanmicSupervisor says “see Supervisor”, but FWIW it does not say “see Supervisor.child_spec/2”. I think it’s pointing to the Supervisor docs in general for more info about child specs. Maybe it could link directly to the child_spec/1 section. Returns a specification to start a dynamic supervisor under a supervisor is very different from what’s written in the Supervisor.child_spec/2 doc. The doc for DynamicSupervisor.child_spec/1 is much more similar to Registry.child_spec/1 or Agent.child_spec/1.

I’ll admit this is maybe a bad or incomplete assumption but gleaned from what I’ve seen written elsewhere on the forum. I think José’s new documentation makes it more clear that DynamicSupervisor is preferred for efficiency of starting and stopping thousands or millions of processes, because there is no specific ordering of them. My takeaway which may be incorrect is that when you add a child spec to a Supervisor it will always be added to the end of the child list and never removed, and shutdown order is always strictly preserved.