Document which program transformations the compiler is allowed to make

[LilithHafner]

The compiler is allowed to (and does) execute a different programs than the ones that are written. For example, emitting a mul instruction here:

function f(a, b)
    c = 0
    for i in 1:a
        c += b
    end
    c
end

The extent of transformations that are allowed (i.e. what semantics are guaranteed to be preserved) should be documented (c++ documents this concept here)

From discussion with @LSchwerdt in https://github.com/JuliaLang/julia/issues/48753#issuecomment-1445859433

[gbaraldi]

I believe we just do Allows any and all code transformations that do not change the observable behavior of the program. since there is no volatile.

[LilithHafner]

We also need a definition of observable. Likely something similar to the :effect_free section of https://docs.julialang.org/en/v1/base/base/#Base.@assume_effects

[LSchwerdt]

Allows any and all code transformations that do not change the observable behavior of the program.

I think this may be implicity stated here. But making it explicit would be nice. That documentation could be limited to single threaded execution, and would be a good basis to expand upon for the multi-threaded case. There, the situation is much more complicated:

• Julia Atomics
• Atomics Manifesto
• LLVM memory access ordering