Document arithmetic overflow behavior for atomic fetch_add and fetch_sub operations

[mbrubeck]

Are these operations guaranteed to wrap on overflow? The documentation currently says nothing.

[nagisa]

undefined behaviour is all we can guarantee, I think.

[nagisa]

Though it might be possible to implement overflow-checked fetch_add/sub in overflow-checked mode by doing CAS under the cover, to match the behaviour of operations with regular integers.

[hanna-kruppe]

LangRef doesn't say anything about overflow. Perhaps LLVM effectively assumes nsw/nuw but since that is not the default for the analogous "normal" operations, it's really impossible to guess. Perhaps ask LLVM developers?

[eefriedman]

The LLVM atomicrmw operations are guaranteed to wrap on overflow. (I would never have guessed that anyone would assume anything else; I'll look into getting it documented.)

[mbrubeck]

undefined behaviour is all we can guarantee, I think.

I hope you mean we guarantee no undefined behavior, since these are all safe functions.

[nagisa]

@mbrubeck usually overflowing an integer during operations is considered to be UB, which is why I said that.

@eefriedman where does LLVM guarantee that?

[eefriedman]

http://llvm.org/docs/LangRef.html#add-instruction : "If the sum has unsigned overflow, the result returned is the mathematical result modulo 2ⁿ, where n is the bit width of the result." Also, it would be impossible to implement C atomic add on top of atomicrmw if it had any other behavior.

[mbrubeck]

usually overflowing an integer during operations is considered to be UB, which is why I said that.

Only in C and C++, right? In Rust, arithmetic overflow is never undefined behavior.

[nagisa]

I don’t remember Rust making any guarantees about things which happen if integers overflow when overflow checks are not enabled, but it might just be me and my bad memory.

[nagisa]

RFC 560 claims overflows are not UB in the C sense of UB, but still are a program error. I think we should strive to have atomics behave similarly.

[hanna-kruppe]

Safe code must never be able to trigger UB. And although "unspecified" results on overflow (i.e., some result which may not be relied on but has no side effects) were considered for a while, the RFC now says that it always wraps:

The operations +, -, *, can underflow and overflow. When checking is enabled this will panic. When checking is disabled this will two's complement wrap.

[Amanieu]

The C++11 atomic ops guarantee wrapping behavior for add and sub (for both signed and unsigned integers). We should do the same.