Skip to content

Commit 0225560

Browse files
authored
Adjust the "Q&A" documentation for Allocated so it's not Mutex-specific. (#1600)
Cleanup of internal docs for `Allocated`. ### Checklist: - [x] Code and documentation should follow the style of the [Style Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md). - [x] If public symbols are renamed or modified, DocC references should be updated.
1 parent acf8538 commit 0225560

File tree

3 files changed

+20
-9
lines changed

3 files changed

+20
-9
lines changed

Sources/Testing/Support/Additions/AtomicAdditions.swift

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ internal import Synchronization
2626
/// Since we don't try to implement the complete ``Synchronization/AtomicRepresentable``
2727
/// protocol, this implementation only supports using a few types that are
2828
/// actually in use in the testing library.
29+
///
30+
/// ## See Also
31+
///
32+
/// - ``Allocated``
33+
/// - ``Mutex``
2934
struct Atomic<Value>: ~Copyable {
3035
/// Storage for the underlying atomic value.
3136
private nonisolated(unsafe) var _address: UnsafeMutablePointer<Value>

Sources/Testing/Support/Additions/MutexAdditions.swift

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,10 @@ internal import Synchronization
2222
/// replicates the interface of that type but is implemented differently (using
2323
/// heap-allocated storage for the underlying lock and the value it guards).
2424
///
25-
/// **Q:** When should I use `Mutex<T>` vs. `Allocated<Mutex<T>>`?
25+
/// ## See Also
2626
///
27-
/// **A (short):** Whenever the compiler lets you use `Mutex<T>`, use that.
28-
///
29-
/// **A (long):** Mutexes can generally be locally allocated when they are
30-
/// function-local, global, or `static`. If your mutex is an instance member
31-
/// of a reference type (a class or actor), you again generally won't need
32-
/// `Allocated`. If, however, you need a mutex to be an instance member of a
33-
/// copyable value type (a structure or enumeration), then it _must_ be boxed
34-
/// with `Allocated` (or something else that moves its storage onto the heap).
27+
/// - ``Allocated``
28+
/// - ``Atomic``
3529
struct Mutex<Value>: Sendable, ~Copyable where Value: ~Copyable {
3630
/// The underlying lock type.
3731
#if !SWT_NO_OS_UNFAIR_LOCK

Sources/Testing/Support/Allocated.swift

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,18 @@
1313
/// Use this class when you have a move-only value such as an instance of
1414
/// ``Mutex`` that you need to store in an aggregate value type such as a
1515
/// copyable structure.
16+
///
17+
/// **Q:** When should I use `T` vs. `Allocated<T>`?
18+
///
19+
/// **A (short):** Whenever the compiler lets you use `T`, use that.
20+
///
21+
/// **A (long):** Move-only values like mutexes and atomics can generally be
22+
/// locally allocated when they are function-local, global, or `static`. If
23+
/// the instance of `T` in question is an instance member of a reference type
24+
/// (a class or actor), you again generally won't need `Allocated`. If,
25+
/// however, you need your instance of `T` to be an instance member of a
26+
/// copyable value type (a structure or enumeration), then it _must_ be boxed
27+
/// with `Allocated` (or something else that moves its storage onto the heap).
1628
final class Allocated<T> where T: ~Copyable {
1729
/// The underlying value.
1830
let value: T

0 commit comments

Comments
 (0)