Metal Shading Language Specification

example, all non-atomic and relaxed atomic stores that happen before a 
memory_order_release
 fence in thread A will be synchronized with non-atomic and relaxed 
atomic loads from the same locations made in thread B after a 
memory_order_acquire
 fence. 
If there exist atomic functions X and Y, both operating on some atomic object M, such that the 
fence in thread A is sequenced before X, X modifies M, Y is sequenced before the fence in 
thread B, and Y reads the value written by X or a value written by any side effect in the 
hypothetical release sequence, X would read if it were a release operation.  
Depending on the value of order, this operation: 
• has no effects, if 
order == memory_order_relaxed 
 
• is an acquire fence, if 
order == memory_order_acquire 
 
• is a release fence, if 
order == memory_order_release 
 
• is both an acquire fence and a release fence, if 
order == memory_order_acq_rel 
 
• is a sequentially consistent acquire and release fence, if 
order == 
memory_order_seq_cst 


atomic_thread_fence
 imposes different synchronization constraints than an atomic store 
operation with the same 
memory_order
. While an atomic store-release operation prevents all 
preceding writes from moving past the store-release, an 
atomic_thread_fence
 with 
memory_order_release
 ordering prevents all preceding writes from moving past all 
subsequent stores.  
5.12.4 
Atomic Functions 
In addition, accesses to atomic objects may establish inter-thread synchronization and order 
non-atomic memory accesses as specified by 
memory_order
. 
In the atomic functions described in section 5.12.4 and its subsections:  
•
A
 refers to one of the atomic types.  
•
C
 refers to its corresponding non-atomic type.  
•
M
 refers to the type of the other argument for arithmetic operations. For atomic integer 

types, 
M
 is 
C
.  
• Functions that address device memory and do not have 
memory_scope
 argument have 

the same semantics as the corresponding functions with the 
memory_scope
 argument 
set to 
device
. Functions that address threadgroup memory and do not have 
memory_scope
 argument have the same semantics as the corresponding functions with 
the 
memory_scope
 argument set to 
threadgroup
. 
Functions listed in section 5.12.4 and its subsections with names that end with 
_explicit
 are 
supported for all versions of Metal: 
atomic_store_explicit
, 
atomic_load_explicit
, 
atomic_exchange_explicit
, 
atomic_compare_exchange_weak_explicit
, 
atomic_fetch_key_explicit
.  
Other functions are only supported on 
ios-metal2.0
: 
atomic_store
, 
atomic_load
, 
atomic_exchange
, 
atomic_compare_exchange_weak
, 
atomic_fetch_key
.  
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
139
174

---

5.12.4.1 
Atomic Store Functions 
These functions atomically replace the value pointed to by 
object
 with 
desired
. 
For all versions of Metal, the following atomic store functions are supported. For all versions of 
Metal, 
memory_order_relaxed
 is supported for order. For 
ios-metal2.0
, 
memory_order_release
 and 
memory_order_seq_cst
 are also supported. Behavior is 
undefined for 
memory_order_acquire
 and 
memory_order_acq_rel
.  
void atomic_store_explicit(threadgroup A* object,  
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order) 
void atomic_store_explicit(volatile threadgroup A* object,  
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order) 
void atomic_store_explicit(device A* object,  
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order) 
void atomic_store_explicit(volatile device A* object,  
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order) 
void atomic_store_explicit(device A* object,  
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order, 
 
 
 
 
    memory_scope scope) 
void atomic_store_explicit(volatile device A* object,  
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order, 
 
 
 
 
    memory_scope scope) 
For
 ios-metal2.0
, the following atomic store functions are also supported. 
memory_order_seq_cst
 is the implied memory order.  
void atomic_store(threadgroup A* object, C desired) 
void atomic_store(volatile threadgroup A* object, C desired) 
void atomic_store(device A* object, C desired) 
void atomic_store(volatile device A* object, C desired) 
5.12.4.2 
Atomic Load Functions 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
140
174

---

These functions atomically obtain the value pointed to by 
object
. 
For all versions of Metal, the following atomic load functions are supported. For all versions of 
Metal, 
memory_order_relaxed
 is supported for order. For 
ios-metal2.0
, 
memory_order_acquire
 and 
memory_order_acq_rel
 are also supported. Behavior is 
undefined for 
memory_order_release
 and 
memory_order_seq_cst
.  
C atomic_load_explicit(const threadgroup A* object, 
 
 
 
  
memory_order order) 
C atomic_load_explicit(const volatile threadgroup A* object, 
 
 
 
 
memory_order order) 
C atomic_load_explicit(const device A* object, 
 
 
 
 
memory_order order) 
C atomic_load_explicit(const volatile device A* object, 
 
 
 
 
memory_order order) 
C atomic_load_explicit(const device A* object, 
 
 
 
 
memory_order order, 
 
 
 
 
memory_scope scope) 
C atomic_load_explicit(const volatile device A* object, 
 
 
 
 
memory_order order, 
 
 
 
 
memory_scope scope) 
For
 ios-metal2.0
, the following atomic load functions are also supported. 
memory_order_seq_cst
 is the implied memory order. 
C atomic_load(const threadgroup A* object) 
C atomic_load(const volatile threadgroup A* object) 
C atomic_load(const device A* object) 
C atomic_load(const volatile device A* object) 
5.12.4.3 
Atomic Exchange Functions 
These functions atomically replace the value pointed to by 
object
 with 
desired
 and return the 
value 
object
 previously held. 
For all versions of Metal, the following atomic exchange functions are supported. For all versions 
of Metal, 
memory_order_relaxed
 is supported for 
order
. For 
ios-metal2.0
, all 
memory_order
 values are available.  
C atomic_exchange_explicit(threadgroup A* object, 
 
 
 
 
    C desired, 
 
 
 
 
    memory_order order) 
C atomic_exchange_explicit(volatile threadgroup A* object, 
 
2017-9-12   |  Copyright © 2017 Apple Inc. All Rights Reserved.  
Page  
 of  
141
174

---