From 5b6a94da5af35a4aa91759cac2f8db7669a6ec2a Mon Sep 17 00:00:00 2001 From: Keno Fischer Date: Fri, 12 Jan 2024 15:20:44 +0100 Subject: [PATCH] docs: Clarify that `donotdelete` does not affect unreachable code (#52869) In generally accepted compiler terminology, dead code is all code that if removed does not affect the observable behavior of the program. However, people sometimes use the phrase dead code to mean *unreachable* code, which is a subset of dead code (being dead because it is never semantically executed). If one assumes that definition, the docstring for `donotdelete` may be confusing, as it may in fact be deleted from the code if it is unreachable (existence or non-existence in the IR is not ever semantically observable in Julia, so there could not be such an intrinsic, but of course knowing that requires a deep understanding of Julia semantics). Add an extra note to the docs to clarify this point. --- base/docs/basedocs.jl | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index b2d81f482b646..bc7d001a06f51 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -3312,7 +3312,7 @@ kw"atomic" This function prevents dead-code elimination (DCE) of itself and any arguments passed to it, but is otherwise the lightest barrier possible. In particular, -it is not a GC safepoint, does model an observable heap effect, does not expand +it is not a GC safepoint, does not model an observable heap effect, does not expand to any code itself and may be re-ordered with respect to other side effects (though the total number of executions may not change). @@ -3330,6 +3330,14 @@ unused and delete the entire benchmark code). `donotdelete(1+1)`, no add instruction needs to be executed at runtime and the code is semantically equivalent to `donotdelete(2).` +!!! note + This intrinsic does not affect the semantics of code that is dead because it is + *unreachable*. For example, the body of the function `f(x) = false && donotdelete(x)` + may be deleted in its entirety. The semantics of this intrinsic only guarantee that + *if* the intrinsic is semantically executed, then there is some program state at + which the value of the arguments of this intrinsic were available (in a register, + in memory, etc.). + # Examples ```julia