Skip to content

Add comments clarifying domain/finaliser guarantees #3938

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion stdlib/domain.mli
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ module Safe : sig
val for_initial_domain : t @@ nonportable
(** [for_initial_domain] is a permanently available [t] that can be used by any
top-level [nonportable] function safely, as such functions can only ever be
executed on the primary domain. *)
executed on the primary (initial) domain. *)
end

type 'a key : value mod portable contended = 'a DLS.key
Expand Down
12 changes: 10 additions & 2 deletions stdlib/gc.mli
Original file line number Diff line number Diff line change
Expand Up @@ -405,8 +405,6 @@ external get_minor_free : unit -> int = "caml_get_minor_free"

@since 4.03 *)

(* CR runtime5: We need finalisers registered on the primary domain to only ever
run on the primary domain. *)
val finalise : ('a -> unit) -> 'a -> unit @@ nonportable
(** [finalise f v] registers [f] as a finalisation function for [v].
[v] must be heap-allocated. [f] will be called with [v] as
Expand All @@ -426,6 +424,12 @@ val finalise : ('a -> unit) -> 'a -> unit @@ nonportable
before the values it depends upon. Of course, this becomes
false if additional dependencies are introduced by assignments.

Finalisers are run by the domain which registered them, unless that
domain has already terminated in which case they may be run by some
other domain. Note that termination of the "primary" (initial) domain
ends the OCaml process, so finalisers registered by the initial domain
will only by run by that domain.

In the presence of multiple OCaml threads it should be assumed that
any particular finaliser may be executed in any of the threads.

Expand Down Expand Up @@ -485,6 +489,10 @@ val finalise_last : (unit -> unit) -> 'a -> unit @@ nonportable
functions attached with {!finalise} are always called before the
finalisation functions attached with {!finalise_last}.

As for {!finalise}, the finaliser is run by the domain which registered it,
unless that domain has already terminated in which case it may be run by
some other domain.

@since 4.04
*)

Expand Down