ATOM_ADD(3clc)

💖 ATOM_ADD (3clc) — the OpenCL manual, but make it make sense 💖

okay bestie, sit down, grab a boba, because we're talking about atom_add — the 64-bit atom_add functions, from the OpenCL manual (3clc). this one is lowkey short but she is IMPORTANT, so pay attention 🫶

---

✨ NAME ✨

atom_add — the 64-bit atom_add functions. that's it, that's the whole vibe. she's 64-bit and she's atomic 💅

---

🌈 SYNOPSIS 🌈

look at these four gorgeous signatures, they're giving overload realness:

long atom_add(volatile global(3clc) long *p, long val);

long atom_add(volatile global(3clc) long *p, long val);

ulong atom_add(volatile local(3clc) ulong *p, ulong val);

ulong atom_add(volatile local(3clc) ulong *p, ulong val);

yes, they appear twice each in the original, and yes, we're keeping them exactly like that. no notes. iconic behavior only 👑

---

💜 DESCRIPTION 💜

okay so here's the whole thing, and honestly it's kind of a serve:

• read the 64-bit value (she's referred to as old, that's her name, respect it) stored at the location pointed to by p
• compute (old + val)
• store the result back at the location pointed to by p
• and then return old — the function returns the original value, not the new one, don't get it twisted bestie

---

now for the part that trips people up EVERY time, no cap: an application that wants to use this extension will need to include this pragma in the OpenCL program source:

#pragma OPENCL EXTENSION cl_khr_int64_base_atomics : enable

don't forget it. i'm literally begging. if you forget it your code will simply not eat 😭

---

this function is performed in one atomic transaction. periodt. ✨

but — and this is the tea — these transactions are atomic for the device executing these atomic functions. so if atomic operations to the same memory location are being performed by kernels executing on multiple devices, there is no guarantee of atomicity. read that again. it's giving "works on my machine" energy. be careful out there 🚨

also, and this is such a fun fact: atomic operations on 64-bit integers, 32-bit integers, and float are also atomic with regard to each other. so they all respect each other, mutual atomicity, we love a supportive ecosystem 💖

---

🌸 SPECIFICATION 🌸

OpenCL Specification[1] — she's specified, she's documented, she's the moment ✨

---

🦋 SEE ALSO 🦋

go read her friends, they're all baddies:

• atomicFunctions(3clc)
• atomic_add(3clc)
• cl_khr_int64_base_atomics(3clc)

---

💅 AUTHORS 💅

The Khronos Group. yes, THE Khronos Group. main character energy fr fr 👑

---

🎀 COPYRIGHT 🎀

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

legal bestie said "share the love, keep the notice" and honestly? fair. respect the license 🫶

---

📝 NOTES 📝

1. OpenCL Specification — page 279, section 6.12.11 - Atomic Functions for 32-bit integers

---

and that's the whole page!! 💖 thank you for coming to my ted talk, go forth and atomically add, and remember: the 64-bit girlies are doing it atomically, and so can you 🧚

signed, sealed, delivered — The Khronos Group, dated 01/14/2021, and this was ATOM_ADD(3clc), the manual page. bye bestie, slay responsibly ⭐🌈