Factor the atomics binary operator sections

Issue #128 resolved
Dan Bonachea created an issue

The API reference sections for the binary operators on atomic_domain<T> are currently pedantically repetitive. Each of them say almost exactly the same thing, with the only difference being the arithmetic operation performed. This is annoying to read (because readers can't easily see if there are any non-trivial operation-specific differences) and tedious to maintain because we have so many needless copies of essentially the same text. This problem will continue to grow worse as we add new atomic operations.

Proposal:

  1. combine all of atomic_domain<T>::fetch_{add,sub,inc,dec} and atomic_domain<T>::{add,sub,inc,dec} into a single section.
  2. The API signature would give exactly two signatures (for the fetching and non-fetching variants) using the shell-like syntax above as shorthand for the function names being prototyped.
  3. Precondition needs to make a generic statement that the operation invoked was included in AD construction (making clear that fetch_op and op are separate operations).
  4. The second paragraph would have a table mapping operation name to C++ syntax operation. This is also the place we might eventually disclaim bitwise equality to the C++ operation semantics for non-integer types and NaNs.
  5. Completion section would make value production conditional on fetch_ variant

load, store and compare_exchange seem sufficiently "different" to merit keeping their own sections, the first two due to unique fencing behavior and the last due to semantic wrinkles with regarding the definition of "equality" that need to be dealt with if/when we introduce non-integer types.

Comments (1)

  1. Log in to comment