Library Moduleswift-atomics 1.3.0Atomics

    Atomics

    An atomics library for Swift.

    Atomics.md
    import Atomics

    Module information

    Declarations
    446
    Symbols
    502

    Coverage

    26.9 percent of the declarations in Atomics are fully documented71.7 percent of the declarations in Atomics are indirectly documented1.3 percent of the declarations in Atomics are completely undocumented

    Declarations

    0.2 percent of the declarations in Atomics are global functions or variables0.9 percent of the declarations in Atomics are operators57.2 percent of the declarations in Atomics are initializers, type members, or enum cases21.3 percent of the declarations in Atomics are instance members1.3 percent of the declarations in Atomics are protocols4.0 percent of the declarations in Atomics are protocol requirements0.4 percent of the declarations in Atomics are default implementations7.4 percent of the declarations in Atomics are structures0.4 percent of the declarations in Atomics are classes6.7 percent of the declarations in Atomics are typealiases

    Interfaces

    99.8 percent of the declarations in Atomics are unrestricted0.2 percent of the declarations in Atomics are underscored
    Module stats and coverage details

    Overview

    This package implements an atomics library for Swift, providing atomic operations for a variety of Swift types, including integers and pointer values. The goal is to enable intrepid developers to start building synchronization constructs directly in Swift.

    Atomic operations aren’t subject to the usual exclusivity rules. The same memory location may be safely read and updated from multiple concurrent threads of execution, as long as all such access is done through atomic operations. For example, here is a trivial atomic counter:

    import Atomics import Dispatch let counter = ManagedAtomic<Int>(0) DispatchQueue.concurrentPerform(iterations: 10) { _ in for _ in 0 ..< 1_000_000 { counter.wrappingIncrement(ordering: .relaxed) } } counter.load(ordering: .relaxed) // ⟹ 10_000_000

    The only way to access the counter value is to use one of the methods provided by ManagedAtomic, each of which implement a particular atomic operation, and each of which require an explicit ordering value. (Swift supports a subset of the C/C++ memory orderings.)

    Features

    The package implements atomic operations for the following Swift constructs, all of which conform to the public AtomicValue protocol:

    • Standard signed integer types (Int, Int64, Int32, Int16, Int8)

    • Standard unsigned integer types (UInt, UInt64, UInt32, UInt16, UInt8)

    • Booleans (Bool)

    • Standard pointer types (UnsafeRawPointer, UnsafeMutableRawPointer, UnsafePointer<T>, UnsafeMutablePointer<T>), along with their optional-wrapped forms (such as Optional<UnsafePointer<T>>)

    • Unmanaged references (Unmanaged<T>, Optional<Unmanaged<T>>)

    • A special DoubleWord type that consists of two UInt values, low and high, providing double-wide atomic primitives

    • Any RawRepresentable type whose RawValue is in turn an atomic type (such as simple custom enum types)

    • Strong references to class instances that opted into atomic use (by conforming to the AtomicReference protocol)

    Of particular note is full support for atomic strong references. This provides a convenient memory reclamation solution for concurrent data structures that fits perfectly with Swift’s reference counting memory management model. (Atomic strong references are implemented in terms of DoubleWord operations.) However, accessing an atomic strong reference is (relatively) expensive, so we also provide a separate set of efficient constructs (ManagedAtomicLazyReference and UnsafeAtomicLazyReference) for the common case of a lazily initialized (but otherwise constant) atomic strong reference.

    Lock-Free vs Wait-Free Operations

    All atomic operations exposed by this package are guaranteed to have lock-free implementations. However, we do not guarantee wait-free operation – depending on the capabilities of the target platform, some of the exposed operations may be implemented by compare-and-exchange loops. That said, all atomic operations map directly to dedicated CPU instructions where available – to the extent supported by llvm & Clang.

    Memory Management

    Atomic access is implemented in terms of dedicated atomic storage representations that are kept distinct from the corresponding regular (non-atomic) type. (E.g., the actual integer value underlying the counter above isn’t directly accessible.) This has several advantages:

    • it helps prevent accidental non-atomic access to atomic variables,

    • it enables custom storage representations (such as the one used by atomic strong references), and

    • it is a better fit with the standard C atomics library that we use to implement the actual operations (as enabled by SE-0282).

    While the underlying pointer-based atomic operations are exposed as static methods on the corresponding AtomicStorage types, we strongly recommend the use of higher-level atomic wrappers to manage the details of preparing/disposing atomic storage. This version of the library provides two wrapper types:

    • an easy to use, memory-safe ManagedAtomic<T> generic class and

    • a less convenient, but more flexible UnsafeAtomic<T> generic struct.

    Both constructs provide the following operations on all AtomicValue types:

    func load(ordering: AtomicLoadOrdering) -> Value func store(_ desired: Value, ordering: AtomicStoreOrdering) func exchange(_ desired: Value, ordering: AtomicUpdateOrdering) -> Value func compareExchange( expected: Value, desired: Value, ordering: AtomicUpdateOrdering ) -> (exchanged: Bool, original: Value) func compareExchange( expected: Value, desired: Value, successOrdering: AtomicUpdateOrdering, failureOrdering: AtomicLoadOrdering ) -> (exchanged: Bool, original: Value) func weakCompareExchange( expected: Value, desired: Value, successOrdering: AtomicUpdateOrdering, failureOrdering: AtomicLoadOrdering ) -> (exchanged: Bool, original: Value)

    Integer types come with additional atomic operations for incrementing or decrementing values and bitwise logical operations. Bool provides select additional boolean operations along the same vein.

    For an introduction to the APIs provided by this package, for now please see the [first version of SE-0282][SE-0282r0].

    Note that when/if Swift gains support for non-copiable types, we expect to replace both ManagedAtomic and UnsafeAtomic with a single move-only atomic struct that combines the performance and versatility of UnsafeAtomic with the ease-of-use and memory safety of ManagedAtomic.

    The current version of the Atomics module does not implement APIs for tagged atomics (see issue #1), although it does expose a DoubleWord type that can be used to implement them. (Atomic strong references are already implemented in terms of DoubleWord, although in their current form they do not expose any user-customizable bits.)

    Atomic Container Types

    Memory Orderings

    Atomic Value Protocols

    • protocol AtomicValue

      A type that supports atomic operations through a separate atomic storage representation.

    • protocol AtomicInteger

      A type that supports atomic integer operations through a separate atomic storage representation.

    • protocol AtomicReference

      A class type that supports atomic strong references.

    • protocol AtomicOptionalWrappable

      An atomic value that also supports atomic operations when wrapped in an Optional. Atomic optional wrappable types come with a standalone atomic representation for their optional-wrapped variants.

    Atomic Storage Representations

    Fences

    Value Types