What is the semantics for choosing the reason when stopping a gen_server?

Question

The Erlang documentation states the following about gen_servers:

...

Note that for any other reason than normal, shutdown, or {shutdown,Term} the gen_server is assumed to terminate due to an error and an error report is issued using error_logger:format/2.

Source: http://www.erlang.org/doc/man/gen_server.html#Module:terminate-2

---

Since anything other than these three reasons are considered an error, I infer that the reasons normal, shutdown and {shutdown, Reason} are considered normal behavior.

I imagine the developers had a motive when choosing these three reasons for stopping a gen_server under normal conditions, but I'm not quite sure how to determine which one to use.

So when should I use normal, shutdown and {shutdown, Reason}?

Answer 1

You should use normal if your server has finished its work and is terminating normally.

shutdown and {shutdown, Reason} are used by supervisor processes when they tell their children to terminate (e.g. the whole app is terminating or another process in the supervision tree has died and this is a one_for_all supervisor).

I use normal for all expected terminations and {error, ErrorDescription} for unexpected terminations.