Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mackron/c89atomic

C89 compatible atomics.
https://github.com/mackron/c89atomic

Last synced: 3 months ago
JSON representation

C89 compatible atomics.

Host: GitHub
URL: https://github.com/mackron/c89atomic
Owner: mackron
Created: 2020-06-22T10:57:47.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2024-04-28T07:42:25.000Z (6 months ago)
Last Synced: 2024-06-12T08:57:12.000Z (5 months ago)
Language: C
Size: 190 KB
Stars: 69
Watchers: 7
Forks: 9
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

awesome-audio-plugin-framework - c89atomic

README

C89 compatible atomics.

This library aims to implement an equivalent to the C11 atomics library. It's intended to be used as a way to
enable the use of atomics in a mostly consistent manner to modern C, while still enabling compatibility with
older compilers. This is *not* a drop-in replacement for C11 atomics, but is very similar. Only limited testing
has been done so use at your own risk. I'm happy to accept feedback and pull requests with bug fixes.

When compiling with GCC and Clang, this library will translate to a one-to-one wrapper around the `__atomic_*`
intrinsics provided by the compiler.

When compiling with Visual C++ things are a bit more complicated because it does not have support for C11 style
atomic intrinsics. This library will try to use the `_Interlocked*` intrinsics instead, and if unavailable will
use inlined assembly (x86 only).

Supported compilers are Visual Studio back to VC6, GCC and Clang. If you need support for a different compiler
I'm happy to add support (pull requests appreciated). This library currently assumes the `int` data type is
32 bits.

Usage
-----
This is a header-only library. Just add `c89atomic.h` to your source tree and include it:

```c
#include "c89atomic.h"
```

Everything is implemented with defines and inline functions. There are no source files or build scripts to
deal with.

Differences With C11
--------------------
For practicality, this is not a drop-in replacement for C11's `stdatomic.h`. Below are the main differences
between c89atomic and stdatomic.

* All operations require an explicit size which is specified by the name of the function, and only 8-,
16-, 32- and 64-bit operations are supported. Objects of an arbitrary sizes are not supported.
* Some extra APIs are included:
- `c89atomic_compare_and_swap_*()`
- `c89atomic_test_and_set_*()`
- `c89atomic_clear_*()`
* All APIs are namespaced with `c89`.
* `c89atomic_*` data types are undecorated.

Compare Exchange
----------------
This library implements a simple compare-and-swap function called `c89atomic_compare_and_swap_*()` which is
slightly different to C11's `atomic_compare_exchange_*()`. This is named differently to distinguish between
the two. `c89atomic_compare_and_swap_*()` returns the old value as the return value, whereas
`atomic_compare_exchange_*()` will return it through a parameter and supports explicit memory orders for
success and failure cases.

With Visual Studio and versions of GCC earlier than 4.7, an implementation of `atomic_compare_exchange_*()`
is included which is implemented in terms of `c89atomic_compare_and_swap_*()`, but there's subtle details to be
aware of with this implementation. Note that the following only applies for Visual Studio and versions of GCC
earlier than 4.7. Later versions of GCC and Clang use the `__atomic_compare_exchange_n()` intrinsic directly
and are not subject to the following.

Below is the 32-bit implementation of `c89atomic_compare_exchange_strong_explicit_32()` which is implemented
the same for the weak versions and other sizes, and only for Visual Studio and old versions of GCC (prior to
4.7):

```c
c89atomic_bool c89atomic_compare_exchange_strong_explicit_32(volatile c89atomic_uint32* dst,
volatile c89atomic_uint32* expected,
c89atomic_uint32 desired,
c89atomic_memory_order successOrder,
c89atomic_memory_order failureOrder)
{
c89atomic_uint32 expectedValue;
c89atomic_uint32 result;

expectedValue = c89atomic_load_explicit_32(expected, c89atomic_memory_order_seq_cst);
result = c89atomic_compare_and_swap_32(dst, expectedValue, desired);
if (result == expectedValue) {
return 1;
} else {
c89atomic_store_explicit_32(expected, result, failureOrder);
return 0;
}
}
```

The call to `c89atomic_store_explicit_32()` is not atomic with respect to the main compare-and-swap operation
which may cause problems when `expected` points to memory that is shared between threads. This only becomes an
issue if `expected` can be accessed from multiple threads at the same time which for the most part will never
happen because a compare-and-swap will almost always be used in a loop with a local variable being used for the
expected value.

If the above is a concern, you should consider reworking your code to use `c89atomic_compare_and_swap_*()`
directly, which is atomic and more efficient. Alternatively you'll need to use a lock to synchronize access
to `expected`, upgrade your compiler, or use a different library.