Contents

swift-atoms/swift-ownership

Use this package when you decide who owns a value, who may look at or change it, and how it moves to another owner or task. Start from Ownership.Unique<Value> for one owner of a heap-allocated value (including ~Copyable ones), Ownership.Box<Value> for a value-semantic heap

Laws

  • Ownership.Box copies share one storage, and so one identity, until a copy is mutated through value. That mutation first gives the copy its own storage by calling the clone closure; the other copies keep the old storage. ensureUnique() returns true exactly when it made such a copy. clone() always makes new storage, shared or not. unguarded reads and writes the current storage without this check.
  • Mutating a shared Ownership.Box whose clone is nil traps. A box of a ~Copyable value without a clone can be copied and read, but only mutated while it is unique.
  • Ownership.Box calls drain once per storage, on the stored value, when the last copy sharing that storage is dropped, and then destroys the value. Storage made by copy-on-write keeps the same drain and clone.
  • Ownership.Borrow(borrowing:) on a Copyable value copies it into a heap buffer that the borrow and its copies keep alive, so later changes to the source are not seen. On a ~Copyable value it points at the value in place. The pointer initializers keep nothing alive: the pointee must outlive the borrow, and with unsafeAddress: or unsafeRawAddress: the pointer must point into storage of the owner argument.
  • Writes through Ownership.Inout.value go straight to the source storage; nothing is copied back later.
  • Ownership.Mutable aliases share one stored value with no synchronization, so it is not Sendable. Ownership.Mutable.Unchecked only asserts that the caller makes cross-task use safe.
  • Ownership.Latch holds at most one value over its whole life. Its states only advance: empty, then full, then taken. take() returns the value to exactly one caller, even under concurrent calls, and nil before a value is stored and after it is taken. store(_:) traps when a value is present or has already been taken. Dropping a full latch destroys its value; after take() the caller owns it.
  • Ownership.Slot is reusable: after take() it is empty and accepts another store(:). It never waits or traps on contention: store(:) hands the value back when the slot is not empty (including while another store or take is in progress), and take() returns nil when it is not full. store(unchecked:), take(unchecked:), Ownership.Slot.Move.in(_:) and Ownership.Slot.Move.out trap in those cases instead. With one producer and one consumer, every stored value is taken exactly once and in order. Dropping a full slot destroys its value.
  • Both state machines publish with release and observe with acquire ordering: a value written by store(_:) is fully visible to the take() that receives it.
  • Ownership.Transfer.Value.Outgoing.Token.take() succeeds once; a second call on any copy of the token traps. An Ownership.Transfer.Value.Incoming.Token or Ownership.Transfer.Retained.Incoming.Token may store once; a second store traps, and so does a store after the receiver has consumed the value. consume() returns nil when nothing was stored yet.
  • Ownership.Transfer.Retained.Outgoing holds one retain of its object. consume() hands that retain to the caller; dropping the outgoing value without consuming it releases the retain. The raw-pointer initializer adopts a pointer that already carries one retain, as from Unmanaged.passRetained, and does not add another.
  • A pointer from Ownership.Transfer.Erased.Outgoing.make(:) must reach exactly one of consume(:) or destroy(:), and consume (directly or through Ownership.Transfer.Erased.Incoming.consume(:)) must name the same type that make stored. destroy(_:) runs the payload's deinitializer without knowing its type. Ownership.Transfer.Erased.Outgoing.Pointer only carries the address across tasks; it owns nothing.

Package Metadata

Repository: swift-atoms/swift-ownership

Default branch: main

README: README.md