Merge pull request #84 from lorentey/finalize-1.1

Update README

Author: lorentey

README.md

@@ -25,6 +25,7 @@ The only way to access the counter value is to use one of the methods provided b
 
 ## Table of Contents
 
+  * [Word of Warning](#word-of-warning)
   * [Getting Started](#getting-started)
   * [Features](#features)
     * [Lock\-Free vs Wait\-Free Operations](#lock-free-vs-wait-free-operations)
@@ -34,6 +35,21 @@ The only way to access the counter value is to use one of the methods provided b
   * [Contributing to Swift Atomics](#contributing-to-swift-atomics)
   * [Development](#development)
 
+## Word of Warning
+
+Atomic values are fundamental to managing concurrency. However, they are far too low level to be used lightly. These things are full of traps. They are extremely difficult to use correctly -- far trickier than, say, unsafe pointers.
+
+The best way to deal with atomics is to avoid directly using them. It's always better to rely on higher-level constructs, whenever possible.
+
+This package exists to support the few cases where the use of atomics is unavoidable -- such as when implementing those high-level synchronization/concurrency constructs.
+
+The primary focus is to provide systems programmers access to atomic operations with an API design that emphasizes clarity over superficial convenience:
+
+- Each atomic operation is invoked in client code using a clear, unabbreviated name that directly specifies what that operation does. Atomic operations are never implicit -- they are always clearly spelled out.
+
+- There is no default memory ordering, to avoid accidental (and costly) use of sequential consistency. (This is surprisingly common issue in C/C++.)
+
+- Operations such as compare/exchange prefer to keep input values cleanly separated from results. There are no `inout` parameters.
 
 ## Getting Started
 
@@ -48,7 +64,7 @@ let package = Package(
   dependencies: [
     .package(
       url: "https://github.com/apple/swift-atomics.git", 
-      .upToNextMajor(from: "1.0.0") // or `.upToNextMinor
+      .upToNextMajor(from: "1.1.0") // or `.upToNextMinor
     )
   ],
   targets: [
@@ -71,7 +87,7 @@ The package implements atomic operations for the following Swift constructs, all
 - 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
+- A special `DoubleWord` type that consists of two `UInt` values, `first` and `second`, 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)
 
@@ -116,6 +132,12 @@ func compareExchange(
     failureOrdering: AtomicLoadOrdering
 ) -> (exchanged: Bool, original: Value)
 
+func weakCompareExchange(
+    expected: Value,
+    desired: Value,
+    ordering: AtomicUpdateOrdering
+) -> (exchanged: Bool, original: Value)
+
 func weakCompareExchange(
     expected: Value,
     desired: Value,
@@ -124,11 +146,106 @@ func weakCompareExchange(
 ) -> (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.
+Integer types come with additional atomic operations for incrementing or decrementing values and bitwise logical operations. 
 
-For an introduction to the APIs provided by this package, for now please see the [first version of SE-0282][SE-0282r0]. 
+```swift
+func loadThenWrappingIncrement(
+    by operand: Value = 1,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func loadThenWrappingDecrement(
+    by operand: Value = 1,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func loadThenBitwiseAnd(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func loadThenBitwiseOr(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
 
-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`.
+func loadThenBitwiseXor(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func wrappingIncrementThenLoad(
+    by operand: Value = 1,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func wrappingDecrementThenLoad(
+    by operand: Value = 1,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func bitwiseAndThenLoad(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func bitwiseOrThenLoad(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func bitwiseXorThenLoad(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+
+func wrappingIncrement(
+    by operand: Value = 1,
+    ordering: AtomicUpdateOrdering
+)
+
+func wrappingDecrement(
+    by operand: Value = 1,
+    ordering: AtomicUpdateOrdering
+)
+```
+
+`Bool` provides select additional boolean operations along the same vein.
+
+```swift
+func loadThenLogicalAnd(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func loadThenLogicalOr(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func loadThenLogicalXor(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func logicalAndThenLoad(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func logicalOrThenLoad(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+
+func logicalXorThenLoad(
+    with operand: Value,
+    ordering: AtomicUpdateOrdering
+) -> Value
+```
+
+For an introduction to the APIs provided by this package, for now please see the [first version of SE-0282][SE-0282r0]. 
 
 The current version of the `Atomics` module does not implement APIs for tagged atomics (see [issue #1](https://github.com/apple/swift-atomics/issues/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.)
 
@@ -138,7 +255,7 @@ The Swift Atomics package is source stable. The version numbers follow [Semantic
 
 [semver]: https://semver.org
 
-The public API of version 1.0 of the `swift-atomics` package consists of non-underscored declarations that are marked `public` in the `Atomics` module.
+The public API of version 1.1 of the `swift-atomics` package consists of non-underscored declarations that are marked `public` in the `Atomics` module.
 
 By "underscored declarations" we mean declarations that have a leading underscore anywhere in their fully qualified name. For instance, here are some names that wouldn't be considered part of the public API, even if they were technically marked public:
 
@@ -149,13 +266,13 @@ By "underscored declarations" we mean declarations that have a leading underscor
 
 Interfaces that aren't part of the public API may continue to change in any release, including patch releases. 
 
-Note that contents of the `_AtomicsShims` module explicitly aren't public API. (As implied by its underscored module name.) The definitions therein may therefore change at whim, and the entire module may be removed in any new release -- do not import this module directly. We also don't make any source compatibility promises about the contents of the `Utilities` and `Tests` subdirectories.
+Note that contents of the `_AtomicsShims` module explicitly aren't public API. (As implied by its underscored module name.) The definitions therein may therefore change at whim, and the entire module may be removed in any new release -- do not import this module directly. We also don't make any source compatibility promises about the contents of the `Utilities`, `Tests`, `Xcode` and `cmake` subdirectories.
 
 If you have a use case that requires using underscored APIs, please [submit a Feature Request][enhancement] describing it! We'd like the public interface to be as useful as possible -- although preferably without compromising safety or limiting future evolution.
 
 Future minor versions of the package may introduce changes to these rules as needed.
 
-We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. (This allows the package to make use of new language/stdlib features, build on compiler bug fixes, and adopt new package manager functionality as soon as they are available.)
+We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, new versions of this package will require clients to upgrade to a more recent Swift toolchain release. (This allows the package to make use of new language/stdlib features, build on compiler bug fixes, and adopt new package manager functionality as soon as they are available.)
 
 Requiring a new Swift release will only require a minor version bump.
 
@@ -196,8 +313,6 @@ A number of [source files](./Sources/Atomics) have a `.swift.gyb` extension. The
 
 To regenerate sources (and to update the inventory of XCTest tests), you need to manually run the script [`generate-sources.sh`](./Utilities/generate-sources.sh) in the Utilities folder of this repository. This needs to be done every time you modify one of the template files.
 
-The same script also runs `swift test --generate-linuxmain` to register any newly added unit tests.
-
 In addition to gyb, the [`_AtomicsShims.h`](./Sources/_AtomicsShims/include/_AtomicsShims.h) header file uses the C preprocessor to define trivial wrapper functions for every supported atomic operation -- memory ordering pairing.
 
 ⚛︎︎