search

elixir-lang / elixir

Elixir is a dynamic, functional language for building scalable and maintainable applications
https://elixir-lang.org/
Apache License 2.0
24.3k stars 3.35k forks source link

Clarify documentation around hibernation #12166

Closed aochagavia closed 1 year ago

aochagavia commented 1 year ago

Elixir and Erlang/OTP versions

All

Operating system

All

Current behavior

The documentation around hibernation in GenServer is unclear regarding the proper use of hibernation. It currently says "it should only be used when a message is not expected soon" (see below for the full text), which is too vague to be actionable.

https://github.com/elixir-lang/elixir/blob/1d39dfbb9d8bd95478d8e78c11420d203fea67e9/lib/elixir/lib/gen_server.ex#L495-L498

Expected behavior

The documentation should more clearly state what we mean by "soon", or at least provide resources to help people discover if hibernation is suitable for their use case. Ideally, we should mention the amount of time (e.g. milliseconds, seconds, minutes) that might pass before the genserver is able to handle the next message, depending on factors like the time spent in garbage collection and the inherent cost of hibernating.

(Sorry for not coming up with numbers myself, I am just a beginner and don't know exactly how hibernation is implemented)

josevalim commented 1 year ago

Hi @aochagavia! There is really no measure for "soon" because there is no magic value that works on all systems. At the same time, I think it is more important to say "we are not expecting a new message to immediately arrive" rather than "soon". The point is to not delay processing of incoming messages due to the hibernation.

aochagavia commented 1 year ago

Thanks for taking the time to respond :). The issue I am facing is that, as a user of Elixir, I would like to know more about what exactly happens when a process hibernates, so I can make the right call when writing my code. The docs give me the uncomfortable sensation that something bad for performance may happen if I use hibernation wrongly, but they don't help me find out what the relevant factors are.

I agree that mentioning a number might not be the right thing, because of the wide range of systems the ERTS may run on, but it would be very helpful to have a more detailed breakdown of the costs of hibernation (for instance: are there other costs to besides the fact that the process is garbage-collected and the heap is compacted? Will the scheduler prioritize non-hibernated processes?)

Maybe this is all because I am not yet as familiar with the language, but I assume other newcomers might want to know more about hibernation and having it in the docs would help. If that is more detail than you think is worth for the official docs, maybe adding a link to some place with more information would be a good alternative.

josevalim commented 1 year ago

I have added more context to the docs but, to answer your questions: there are no additional cost besides the one mentioned. Hibernation also does not lead to priorization.

I think the most important though is that it is a tool you each for. You will hibernate if memory usage is high and the process may not immediately expect messages (the first part being the most important criteria).

aochagavia commented 1 year ago

Great, thanks a lot!