Skip to content

Commit 5b6a94d

Browse files
authored
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.
1 parent 270ea64 commit 5b6a94d

File tree

1 file changed

+9
-1
lines changed

1 file changed

+9
-1
lines changed

base/docs/basedocs.jl

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3312,7 +3312,7 @@ kw"atomic"
33123312
33133313
This function prevents dead-code elimination (DCE) of itself and any arguments
33143314
passed to it, but is otherwise the lightest barrier possible. In particular,
3315-
it is not a GC safepoint, does model an observable heap effect, does not expand
3315+
it is not a GC safepoint, does not model an observable heap effect, does not expand
33163316
to any code itself and may be re-ordered with respect to other side effects
33173317
(though the total number of executions may not change).
33183318
@@ -3330,6 +3330,14 @@ unused and delete the entire benchmark code).
33303330
`donotdelete(1+1)`, no add instruction needs to be executed at runtime and
33313331
the code is semantically equivalent to `donotdelete(2).`
33323332
3333+
!!! note
3334+
This intrinsic does not affect the semantics of code that is dead because it is
3335+
*unreachable*. For example, the body of the function `f(x) = false && donotdelete(x)`
3336+
may be deleted in its entirety. The semantics of this intrinsic only guarantee that
3337+
*if* the intrinsic is semantically executed, then there is some program state at
3338+
which the value of the arguments of this intrinsic were available (in a register,
3339+
in memory, etc.).
3340+
33333341
# Examples
33343342
33353343
```julia

0 commit comments

Comments
 (0)