Skip to content

Commit 0db308c

Browse files
committed
Clarify @on_load will be called early on releases, closes #14960
1 parent 35a7e3a commit 0db308c

File tree

1 file changed

+8
-17
lines changed

1 file changed

+8
-17
lines changed

lib/elixir/lib/module.ex

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -402,30 +402,21 @@ defmodule Module do
402402
403403
Accepts the function name (as an atom) of a function in the current module.
404404
The function must have an arity of 0 (no arguments). If the function does
405-
not return `:ok`, the loading of the module will be aborted.
406-
For example:
405+
not return `:ok`, the loading of the module will be aborted. Its primary
406+
use case is to load [NIFs](https://www.erlang.org/doc/man/erl_nif):
407407
408408
defmodule MyModule do
409-
@on_load :load_check
410-
411-
def load_check do
412-
if some_condition() do
413-
:ok
414-
else
415-
:abort
416-
end
417-
end
409+
@on_load :load_external_code
418410
419-
def some_condition do
420-
false
411+
def load_external_code do
412+
:erlang.load_nif(~c"path/to/extension.so_or_dll")
421413
end
422414
end
423415
424416
The function given to `on_load` should avoid calling functions from
425-
other modules. If you must call functions in other modules and those
426-
modules are defined within the same project, the called modules must
427-
have the `@compile {:autoload, true}` annotation, so they are loaded
428-
upfront (and not from within the `@on_load` callback).
417+
other modules. This is because, when running a `mix release`,
418+
`on_load` runs extremely early, before any application starts running,
419+
and therefore even systems like the `Logger` and `IO` are not yet available.
429420
430421
### `@vsn`
431422

0 commit comments

Comments
 (0)