LIBATOMIC-OPS(3)

✨ NAME ✨

libatomic-ops — bestie, it's literally a library that hands you user level atomic operations 💅

🌸 SYNOPSIS 🌸

#include <atomic_ops.h>

cc ... -latomic_ops

okay so real talk: all of these operations have an extra barrier option that you can set explicitly, so keep that in mind 🫶

void AO_load(AO_t *addr)
void AO_store(AO_t *addr, AO_t val)

int AO_test_and_set (AO_t *addr)

AO_t AO_fetch_and_add(AO_t *addr, AO_t incr)
AO_t AO_fetch_and_add1(AO_t *addr)
AO_t AO_fetch_and_sub1(AO_t *addr)

void AO_or(AO_t *p, AO_t incr)
int AO_compare_and_swap(AO_t *addr, AO_t old, AO_t new_val)

🦋 DESCRIPTION 🦋

libatomic-ops is your programming interface to a comprehensive range of atomic operations at user level. no cap, it's a whole buffet 🔥

We define various atomic operations on memory in a machine-specific way. And unfortunately — as is tradition 😭 — this gets complicated, because these might or might not be combined with various memory barriers. So the actual operations we define have the form AO_<atomic-op>_<barrier> for all plausible combinations of <atomic-op> and <barrier>. it's giving ✨combinatorics✨

🎀 the valid barrier suffixes 🎀

• _release — earlier operations may not be delayed past it.
• _acquire — later operations may not move ahead of it.
• _read — subsequent reads must follow this operation and preceding reads.
• _write — earlier writes precede both this operation and later writes.
• _full — ordered with respect to both earlier and later memops.
• _release_write — ordered with respect to earlier writes.
• _acquire_read — ordered with respect to later reads.

This of course results in a mild combinatorial explosion 💀

The library will find the least expensive way to implement your operations on the applicable hardware. In many cases that will involve, for example, a stronger memory barrier, or a combination of hardware primitives. she's efficient, she's resourceful, she's the moment 👑

⚠️ real talk, do NOT skip this part: atomicity guarantees are valid only if both readers and writers use AO_ operations to access the shared value, while ordering constraints are intended to apply to all memory operations. If a location can potentially be accessed simultaneously from multiple threads, and one of those accesses may be a write access, then all such accesses to that location should be through AO_ primitives. However if AO_ operations enforce sufficient ordering to ensure that a location x cannot be accessed concurrently, or can only be read concurrently, then x can be accessed via ordinary references and assignments. 🫶

All operations operate on an AO_t value, which is the natural word size for the architecture. slay 🎀

• AO_load and AO_store — load and store the specified pointer address.
• AO_test_and_set — atomically replaces an address with AO_TS_SET and returns the prior value. An AO_TS_t location can be reset with the AO_CLEAR macro, which usually uses AO_store_release 💅
• AO_fetch_and_add — takes an address and a value to add.
• AO_fetch_and_add1 and AO_fetch_and_sub1 — provided since they may have faster implementations on some hardware 🏎️
• AO_or — atomically ors an AO_t value into a memory location, but does not provide access to the original. no receipts, sorry bestie 🙈
• AO_compare_and_swap — takes an address, an old value and a new value and returns an int. non-zero indicates the compare and swap succeeded ✨

👀 SEE ALSO 👀

libatomic-stack(3), libatomic-malloc(3)

💜 AUTHOR 💜

This manual page was written by Ian Wienand <ianw@gelato.unsw.edu.au>, based on comments in the source code. It was written for the Debian project (but may be used by others). icon behavior, fr fr 👑

okay that's the whole page bestie, and here's the lil sign-off 💖 this one's from Ian Wienand, dated May 17, 2005, and it lives in the LIBATOMIC-OPS(3) section of the manual. go forth and be atomic 🦋✨