atomic · Standard Library

Memory-order markers and fixed-width integer atomic operations over one referenced integer object.

The generic operations call imported C-ABI functions implemented in atomic.ll in the library root. A program that calls them must be linked with that file, for example clang program.ll path/to/mpl-sl/atomic.ll -o program; otherwise the linker reports undefined references such as atomicExchangeN8Acquire.

Memory orders

ACQUIRE: acquire-order marker.
RELEASE: release-order marker.

Fields

MEMORY_ORDER: static empty-structure marker.
ORDER: static Text, respectively "acquire" for ACQUIRE and "release" for RELEASE.

`ACQUIRE`

(-- order) Provides the acquire-order marker for atomicLoad, atomicExchange, atomicOr, and atomicXor.

Selects LLVM acquire ordering; atomicStore does not accept this marker.
Selection is by marker schema; supplying an order-name Text string does not select an order.

`RELEASE`

(-- order) Provides the release-order marker for atomicStore, atomicExchange, atomicOr, and atomicXor.

Selects LLVM release ordering; atomicLoad does not accept this marker.
Selection is by marker schema; supplying an order-name Text string does not select an order.

Examples

"atomic"  use
"control" use

{} () {} [
  ACQUIRE printStack _:;
  RELEASE printStack _:;
] "main" exportFunction

Expected Output During Compilation

{
  MEMORY_ORDER: ();
  ORDER: "acquire" virtual;
}
{
  MEMORY_ORDER: ();
  ORDER: "release" virtual;
}

Supported schemas

Accepted schemas are Int8, Int16, Int32, Int64, Nat8, Nat16, Nat32, and Nat64.
Intx and Natx are not supported.
Each operation requires the referenced object and the written value, if present, to use the same supported fixed-width integer schema.

Operation summary

atomicLoad accepts only ACQUIRE.
atomicStore accepts only RELEASE.
atomicExchange, atomicOr, and atomicXor accept ACQUIRE and RELEASE.
Nat operations preserve the same schema in results.
Int schemas are accepted, but atomicLoad, atomicExchange, atomicOr, and atomicXor return the corresponding same-width Nat schema.

`refCast`

(ref schema -- castRef) Returns a reference at ref's storage address using the schema supplied by schema.

Does not copy or convert stored bytes. The result is immutable if ref or the supplied schema view is immutable; otherwise it permits mutable access.
Before accessing the result, the caller must ensure that the storage is live, large enough and correctly aligned for the selected schema.

Native bindings

These C-ABI bindings take no order marker. The first C parameter is the top stack item, so ref is above source in each written-value effect. See the generic operation rules.

For each native binding, Nw in its name selects Natw for the source, referenced item and any returned value. Load bindings accept immutable or mutable references; writes require mutable references.

Exchange bindings

`atomicExchangeN8Acquire`	`(source ref -- previousValue)`	Atomically exchanges `Nat8` source with ref using acquire ordering and returns the previous value.
`atomicExchangeN16Acquire`	`(source ref -- previousValue)`	Atomically exchanges `Nat16` source with ref using acquire ordering and returns the previous value.
`atomicExchangeN32Acquire`	`(source ref -- previousValue)`	Atomically exchanges `Nat32` source with ref using acquire ordering and returns the previous value.
`atomicExchangeN64Acquire`	`(source ref -- previousValue)`	Atomically exchanges `Nat64` source with ref using acquire ordering and returns the previous value.
`atomicExchangeN8Release`	`(source ref -- previousValue)`	Atomically exchanges `Nat8` source with ref using release ordering and returns the previous value.
`atomicExchangeN16Release`	`(source ref -- previousValue)`	Atomically exchanges `Nat16` source with ref using release ordering and returns the previous value.
`atomicExchangeN32Release`	`(source ref -- previousValue)`	Atomically exchanges `Nat32` source with ref using release ordering and returns the previous value.
`atomicExchangeN64Release`	`(source ref -- previousValue)`	Atomically exchanges `Nat64` source with ref using release ordering and returns the previous value.

Load bindings

`atomicLoadN8Acquire`	`(ref -- loadedValue)`	Atomically loads `Nat8` from ref with acquire ordering.
`atomicLoadN16Acquire`	`(ref -- loadedValue)`	Atomically loads `Nat16` from ref with acquire ordering.
`atomicLoadN32Acquire`	`(ref -- loadedValue)`	Atomically loads `Nat32` from ref with acquire ordering.
`atomicLoadN64Acquire`	`(ref -- loadedValue)`	Atomically loads `Nat64` from ref with acquire ordering.

Or bindings

`atomicOrN8Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat8` source to ref using acquire ordering and returns the previous value.
`atomicOrN16Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat16` source to ref using acquire ordering and returns the previous value.
`atomicOrN32Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat32` source to ref using acquire ordering and returns the previous value.
`atomicOrN64Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat64` source to ref using acquire ordering and returns the previous value.
`atomicOrN8Release`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat8` source to ref using release ordering and returns the previous value.
`atomicOrN16Release`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat16` source to ref using release ordering and returns the previous value.
`atomicOrN32Release`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat32` source to ref using release ordering and returns the previous value.
`atomicOrN64Release`	`(source ref -- previousValue)`	Atomically applies bitwise OR of `Nat64` source to ref using release ordering and returns the previous value.

Store bindings

`atomicStoreN8Release`	`(source ref --)`	Atomically stores `Nat8` source into ref with release ordering.
`atomicStoreN16Release`	`(source ref --)`	Atomically stores `Nat16` source into ref with release ordering.
`atomicStoreN32Release`	`(source ref --)`	Atomically stores `Nat32` source into ref with release ordering.
`atomicStoreN64Release`	`(source ref --)`	Atomically stores `Nat64` source into ref with release ordering.

Xor bindings

`atomicXorN8Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat8` source to ref using acquire ordering and returns the previous value.
`atomicXorN16Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat16` source to ref using acquire ordering and returns the previous value.
`atomicXorN32Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat32` source to ref using acquire ordering and returns the previous value.
`atomicXorN64Acquire`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat64` source to ref using acquire ordering and returns the previous value.
`atomicXorN8Release`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat8` source to ref using release ordering and returns the previous value.
`atomicXorN16Release`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat16` source to ref using release ordering and returns the previous value.
`atomicXorN32Release`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat32` source to ref using release ordering and returns the previous value.
`atomicXorN64Release`	`(source ref -- previousValue)`	Atomically applies bitwise XOR of `Nat64` source to ref using release ordering and returns the previous value.

To access an existing integer object, pass a reference to it as ref. atomicLoad accepts immutable or mutable access; atomicExchange, atomicOr, atomicStore, and atomicXor require mutable access. An in-place integer supplied as ref designates temporary storage. The referenced storage must be live and correctly aligned for its integer width; a NIL reference is not a valid target. The load/store bindings require alignments of 1, 2, 4 and 8 bytes for widths 8, 16, 32 and 64. Returned numbers are independent values, not references. Missing atomic.ll definitions cause a native link error, not an MPL overload error.

`atomicExchange`

(source ref order -- previousValue) Atomically stores source through ref and returns the previous value.

See the generic operation rules.

source and ref must use the same supported fixed-width integer schema.
Nat inputs return the previous value with the same schema.
Int inputs return the previous value with the corresponding same-width Nat schema.
order must be ACQUIRE or RELEASE.

`atomicLoad`

(ref order -- loadedValue) Atomically loads the current value from ref.

See the generic operation rules.

ref must use one supported fixed-width integer schema.
Nat inputs return the same schema.
Int inputs return the corresponding same-width Nat schema.
order must be ACQUIRE.

`atomicOr`

(source ref order -- previousValue) Atomically applies bitwise OR with source to ref and returns the previous value.

See the generic operation rules.

source and ref must use the same supported fixed-width integer schema.
Nat inputs return the previous value with the same schema.
Int inputs return the previous value with the corresponding same-width Nat schema.
order must be ACQUIRE or RELEASE.

`atomicStore`

(source ref order --) Atomically stores source through ref.

See the generic operation rules.

source and ref must use the same supported fixed-width integer schema.
order must be RELEASE.

`atomicXor`

(source ref order -- previousValue) Atomically applies bitwise XOR with source to ref and returns the previous value.

See the generic operation rules.

source and ref must use the same supported fixed-width integer schema.
Nat inputs return the previous value with the same schema.
Int inputs return the previous value with the corresponding same-width Nat schema.
order must be ACQUIRE or RELEASE.

Memory orders

Fields

Examples

Expected Output During Compilation

Supported schemas

Operation summary

Native bindings

Exchange bindings

Load bindings

Or bindings

Store bindings

Xor bindings

See also