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.Boxcopies share one storage, and so oneidentity, until a copy is mutated throughvalue. That mutation first gives the copy its own storage by calling thecloneclosure; the other copies keep the old storage.ensureUnique()returnstrueexactly when it made such a copy.clone()always makes new storage, shared or not.unguardedreads and writes the current storage without this check.- Mutating a shared
Ownership.Boxwhosecloneisniltraps. A box of a~Copyablevalue without a clone can be copied and read, but only mutated while it is unique. Ownership.Boxcallsdrainonce 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 samedrainandclone.Ownership.Borrow(borrowing:)on aCopyablevalue 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~Copyablevalue it points at the value in place. The pointer initializers keep nothing alive: the pointee must outlive the borrow, and withunsafeAddress:orunsafeRawAddress:the pointer must point into storage of theownerargument.- Writes through
Ownership.Inout.valuego straight to the source storage; nothing is copied back later. Ownership.Mutablealiases share one stored value with no synchronization, so it is notSendable.Ownership.Mutable.Uncheckedonly asserts that the caller makes cross-task use safe.Ownership.Latchholds 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, andnilbefore 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; aftertake()the caller owns it.Ownership.Slotis reusable: aftertake()it is empty and accepts anotherstore(:). 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), andtake()returnsnilwhen it is not full.store(unchecked:),take(unchecked:),Ownership.Slot.Move.in(_:)andOwnership.Slot.Move.outtrap 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 thetake()that receives it. Ownership.Transfer.Value.Outgoing.Token.take()succeeds once; a second call on any copy of the token traps. AnOwnership.Transfer.Value.Incoming.TokenorOwnership.Transfer.Retained.Incoming.Tokenmay store once; a second store traps, and so does a store after the receiver has consumed the value.consume()returnsnilwhen nothing was stored yet.Ownership.Transfer.Retained.Outgoingholds 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 fromUnmanaged.passRetained, and does not add another.- A pointer from
Ownership.Transfer.Erased.Outgoing.make(:)must reach exactly one ofconsume(:)ordestroy(:), andconsume(directly or throughOwnership.Transfer.Erased.Incoming.consume(:)) must name the same type thatmakestored.destroy(_:)runs the payload's deinitializer without knowing its type.Ownership.Transfer.Erased.Outgoing.Pointeronly carries the address across tasks; it owns nothing.
Package Metadata
Repository: swift-atoms/swift-ownership
Default branch: main
README: README.md