[Docs] Actors and locks: benchmark, lock census of the frame and rules

Examples/ConcurrencyBench/.gitignore

@@ -0,0 +1 @@
+.build/

Examples/ConcurrencyBench/Package.swift

@@ -0,0 +1,12 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+/// Standalone on purpose: it needs macOS 15 for `Synchronization.Mutex`, which is
+/// above the engine's minimum, and it does not depend on the engine.
+let package = Package(
+    name: "ConcurrencyBench",
+    platforms: [.macOS(.v15)],
+    targets: [
+        .executableTarget(name: "ConcurrencyBench", swiftSettings: [.swiftLanguageMode(.v5)]),
+    ]
+)

Examples/ConcurrencyBench/README.md

@@ -0,0 +1,23 @@
+# ConcurrencyBench
+
+Measures what a Swift actor costs next to the lock mechanisms the engine can use
+(`NSLock`, `NSRecursiveLock`, `OSAllocatedUnfairLock`, `Synchronization.Mutex`,
+a serial `DispatchQueue`). It does not depend on the engine.
+
+Results and the rules drawn from them: `docs/proposals/ActorsAndLocks.md`.
+
+```bash
+swift run -c release --package-path Examples/ConcurrencyBench
+```
+
+Pass a section number to run one section:
+
+| Section | What it measures |
+|---|---|
+| 1 | One access from a synchronous thread, no contention |
+| 2 | One access from an async caller, no contention |
+| 3 | 2, 4 and 8 workers on one shared state |
+| 4 | How long a synchronous thread waits for one value, with the thread pool idle and saturated |
+| 5 | One system pass over 10,000 entities |
+
+Needs macOS 15 (for `Mutex`). Always run a release build; each row prints the minimum and the median of its runs.