Ambiguity in documentation concerning :id in supervisor child specification

The documentation for supervisor child specification says the following:

The child specification contains 6 keys. The first two are required, and the remaining ones are optional:

  • :id - any term used to identify the child specification internally by the supervisor; defaults to the given module. In the case of conflicting :id values, the supervisor will refuse to initialize and require explicit IDs. This key is required.

(Source: https://hexdocs.pm/elixir/Supervisor.html)

How can something both be required and have a default value? Does “default” have a special meaning in Elixir that’s different from the mainstream one?

Welcome to the forum!

Default just means that a value will be provided for you if you don’t explicitly give one (under certain conditions) - this is not in conflict with being required. The default ensures that there will always be a value.

I think the confusing bit is that default is usually used with optional arguments. One could argue that by providing a default value the argument is in fact no longer optional - what is optional is that you no longer have to be explicit about it’s value.

Thanks for your speedy answer.

I’m sorry, but I stil don’t get it. When is the default value used if a parameter always has to be supplied, overriding it? Furthermore, omitting the :id in a child specification gives me the following error:

** (MatchError) no match of right hand side value: {:error, {:start_spec, :missing_id}}
lib/supertest.ex:33: (module)
(stdlib) erl_eval.erl:680: :erl_eval.do_apply/6

Granted I haven’t tried it that way, what does your child spec look like?

children = [
  # The Stack is a child started via Stack.start_link([:hello])
  %{
    id: Stack,
    start: {Stack, :start_link, [[:hello]]}
  }
]

Note that the above is equivalent to

children = [
  {Stack, [:hello]}
]

defaults to the given module

Given that phrasing I would try:

children = [
  %{
    start: {Stack, :start_link, [[:hello]]}
  }

Hypothetically the module could be taken from the :start value - whether or not that is happening I don’t know.

If that fails I have to wonder whether “defaults to the given module” actually refers to the tuple notation rather than the child spec map - as in "the module name will be also be used as the id".

The other possibility is that it is trying to convey the convention of using the module name as the id for a singleton process (which is what the tuple notation is doing).

Since I’m experimenting with the Stack example, the code you suggest is identical to the one that causes the above error message (should’ve posted my code, sorry!). However, the tuple version works just fine.

If that fails I have to wonder whether “ defaults to the given module ” actually refers to the tuple notation rather than the child spec map - as in " the module name will be also be used as the id ".

The other possibility is that it is trying to convey the convention of using the module name as the id for a singleton process (which is what the tuple notation is doing).

Both sound likely. Isn’t that quite misleading, though? If it’s a convention, then it should explicitly be described as such. If it refers to the tuple notation it’s not very helpful, because it hasn’t even been introduced at that point (it’s described many paragraphs further down.)

It is indeed a bit confusing.

Child specs (as in instances of the child_spec/0 type) require an :id value always.

However, writing a child spec by hand is error prone (not to mention a pain), and therefore there are functions to create/alter child specs for us: https://hexdocs.pm/elixir/Supervisor.html#child_spec/2 It is in fact for this function that :id values are optional (i.e. don’t have to be given to the overrides) and for which a default value will be given if absent.

In other words, calling Supervisor.child_spec({MyModule, [foo: :bar]}) will result in a child spec with id MyModule, whereas calling Supervisor.child_spec({MyModule, [foo: :bar]}, id: :my_id) will return a child spec with id :my_id.

If you want to learn more about Supervisors, child specs, etc. you may find my blog series on the subject to be worth a read: http://davidsulc.com/blog/2018/07/09/pooltoy-a-toy-process-pool-manager-in-elixir-1-6/ (especially “customizing the child spec” at http://davidsulc.com/blog/2018/07/10/pooltoy-a-toy-process-pool-manager-in-elixir-1-6-part-1-9/).

If you want to learn more about Supervisors, child specs, etc. you may find my blog series on the subject to be worth a read: http://davidsulc.com/blog/2018/07/09/pooltoy-a-toy-process-pool-manager-in-elixir-1-6/ (especially “customizing the child spec” at http://davidsulc.com/blog/2018/07/10/pooltoy-a-toy-process-pool-manager-in-elixir-1-6-part-1-9/).

Thanks! Just began reading, but it looks very promising. That’s the thoroughness I wish all tutorials possessed.