https://github.com/glessard/catomics
C11 atomics for Swift
https://github.com/glessard/catomics
atomics concurrency se-0282 swift
Last synced: 3 months ago
JSON representation
C11 atomics for Swift
- Host: GitHub
- URL: https://github.com/glessard/catomics
- Owner: glessard
- License: bsd-3-clause
- Created: 2020-12-03T23:30:18.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2020-12-05T01:31:57.000Z (about 5 years ago)
- Last Synced: 2025-10-17T09:55:34.716Z (3 months ago)
- Topics: atomics, concurrency, se-0282, swift
- Language: Swift
- Homepage:
- Size: 605 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CAtomics [](https://travis-ci.org/glessard/CAtomics)
Some atomic functions made available to Swift 3.1 and up, including Swift 5.3
This project bridges a subset of Clang's C11 atomics support to Swift, in a manner compatible with [SE-0282](https://github.com/apple/swift-evolution/blob/main/proposals/0282-atomics.md). This package has been the underlying guts of the long-standing (but now deprecated) [SwiftAtomics](https://github.com/glessard/swift-atomics) package since 2017.
### Module CAtomics
`CAtomics` provides atomic operations to Swift using a C-style interface.
`CAtomics` implements the following types:
- `AtomicRawPointer`, `AtomicMutableRawPointer`, `AtomicOpaquePointer`, and versions for `Optional` pointers (`AtomicOptionalRawPointer`, etc.);
- `AtomicInt` and `AtomicUInt`, as well as signed and unsigned versions of the 8-bit, 16-bit, 32-bit and 64-bit integer types;
- `AtomicBool`
Functions defined in `CAtomics` are prefixed with `CAtomics`. All types define `CAtomicsLoad`, `CAtomicsStore`, `CAtomicsExchange`, `CAtomicsCompareAndExchangeWeak` and `CAtomicsCompareAndExchangeStrong`. Additionally, the integer types define `CAtomicsAdd`, `CAtomicsSubtract`, `CAtomicsBitwiseAnd`, `CAtomicsBitwiseOr` and `CAtomicsBitwiseXor`. Finally, `AtomicBool` defines `CAtomicsAnd`, `CAtomicsOr`, and `CAtomicsXor`.
The memory ordering (from ``) can be set by using the `order: MemoryOrder` parameter on each method.
```swift
public enum MemoryOrder : UInt32 {
case relaxed, acquire, release, acqrel, sequential
}
```
Note that `memory_order_consume` has no equivalent in this module, as (as far as I can tell) clang silently upgrades that ordering to `memory_order_acquire`, making it impossible (at the moment) to test whether an algorithm can properly use `memory_order_consume`. This also means nothing is lost by its absence.
#### Notes on atomics and the law-of-exclusivity:
Atomic types are useful as synchronization points between threads, and therefore have an interesting relationship with Swift's exclusivity checking. They should be initialized at fixed memory locations, such as members of reference types, captured by closures, or in heap allocations. This being said, although the first two work as expected with current Swift, only the latter (heap allocations) is compatible with the thread sanitizer.
In order to use atomics in a way that is acceptable to the thread sanitizer, one must allocate memory for atomic variables using `UnsafeMutablePointer`. Then, pass that pointer to the functions defined in the `CAtomics` module, as needed.
```swift
import CAtomics
class Example {
private var counter = UnsafeMutablePointer.allocate(capacity: 1)
init() {
CAtomicsInitialize(counter, 0)
}
deinit {
counter.deallocate()
}
func increment(by value: Int = 1) {
CAtomicsAdd(counter, value, .relaxed)
}
}
```
#### Requirements
This library requires Swift 3.1 or later. On Linux, it also requires Clang 3.6 or later.