Description

The following operations perform arithmetic and bitwise computations. All of these operations are applicable to an object of any atomic integer type. The key, operator, and computation correspondence is given in table below:

key op computation

add

+

addition

sub

-

subtraction

or

|

bitwise inclusive or

xor

^

bitwise exclusive or

and

&

bitwise and

min

min

compute min

max

max

compute max

For atomic_fetch and modify functions with key = add or sub on atomic types atomic_intptr_t and atomic_uintptr_t, M is ptrdiff_t. For atomic_fetch and modify functions with key = or, xor, and, min and max on atomic type atomic_intptr_t, M is intptr_t, and on atomic type atomic_uintptr_t, M is uintptr_t.

 
// Requires OpenCL C 3.0 or newer and both the __opencl_c_atomic_order_seq_cst
// and __opencl_c_atomic_scope_device features.
C atomic_fetch_key(volatile __global A *object, M operand)
C atomic_fetch_key(volatile __local A *object, M operand)

// Requires OpenCL C 2.0, or all of the __opencl_c_generic_address_space,
// __opencl_c_atomic_order_seq_cst and __opencl_c_atomic_scope_device features.
C atomic_fetch_key(volatile A *object, M operand)

// Requires OpenCL C 3.0 or newer and the __opencl_c_atomic_scope_device feature.
C atomic_fetch_key_explicit(volatile __global A *object,
                            M operand,
                            memory_order order)
C atomic_fetch_key_explicit(volatile __local A *object,
                            M operand,
                            memory_order order)

// Requires OpenCL C 2.0 or OpenCL C 3.0 or newer and both the
// __opencl_c_generic_address_space and __opencl_c_atomic_scope_device
// features.
C atomic_fetch_key_explicit(volatile A *object,
                            M operand,
                            memory_order order)

// Requires OpenCL C 3.0 or newer.
C atomic_fetch_key_explicit(volatile __global A *object,
                            M operand,
                            memory_order order,
                            memory_scope scope)
C atomic_fetch_key_explicit(volatile __local A *object,
                            M operand,
                            memory_order order,
                            memory_scope scope)

// Requires OpenCL C 2.0, or OpenCL C 3.0 or newer and the
// __opencl_c_generic_address_space feature.
C atomic_fetch_key_explicit(volatile A *object,
                            M operand,
                            memory_order order,
                            memory_scope scope)

Atomically replaces the value pointed to by object with the result of the computation applied to the value pointed to by object and the given operand. Memory is affected according to the value of order. These operations are atomic read-modify-write operations (as defined by section 5.1.2.4 of the C11 Specification). For signed integer types, arithmetic is defined to use two’s complement representation with silent wrap-around on overflow; there are no undefined results. For address types, the result may be an undefined address, but the operations otherwise have no undefined behavior. Returns atomically the value pointed to by object immediately before the effects.

The non-explicit atomic_fetch_key functions require support for OpenCL C 2.0, or OpenCL C 3.0 or newer and both the __opencl_c_atomic_order_seq_cst and __opencl_c_atomic_scope_device features. For the explicit variants, memory order and scope enumerations must respect the restrictions section below.
The function variants that use the generic address space, i.e. no explicit address space is listed, require support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the __opencl_c_generic_address_space feature.

See Also

atomicFunctions, atomicTypes, atomic_compare_exchange, atomic_exchange, atomic_fetch_key, atomic_flag, atomic_flag_clear, atomic_flag_test_and_set, atomic_flag_test_and_set_explicit, atomic_init, atomic_load, atomic_store, atomic_work_item_fence

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0