RcBox

public struct RcBox[T] { /* private fields */ }

Heap allocation with a strong-reference count, used as the underlying storage for the stdlib's copy-on-write types.

String, Array, and Dictionary all wrap an RcBox so that a plain assignment shares storage and only the first mutating call pays for a deep copy. Reach for RcBox directly when building a similar COW type; for plain shared ownership without mutation prefer a more purpose-built container.

Examples

let a = RcBox(value: [1, 2, 3]);
let b = a.clone();          // shares storage; refCount == 2
if b.isUnique() { ... } else { let c = b.deepClone(); /* ... */ }

Representation

One Pointer[RcBoxStorage[T]]. The pointed-to block holds an Int64 refcount followed by the T value, allocated via SystemAllocator.

Memory Model

Reference-counted, non-atomic (today — see TODOs). clone() increments the count and shares storage; deinit decrements and frees on zero. deepClone() allocates a fresh RcBox carrying a copied value.

Guarantees

isUnique() returning true means in-place mutation is safe; this is how COW types decide whether to copy.
The refcount is currently not atomic, so RcBox is not safe to share across threads.

Associated Types

type Target = T

Initializers

public init(consuming T)

Allocates fresh storage holding value with refcount 1. Panics if the underlying SystemAllocator returns .None.

Errors

Panics with "RcBox allocation failed" on allocation failure.

Methods

public func deepClone() -> RcBox[T]

Allocates fresh storage with a copy of the value. Used by COW types when isUnique() returns false — splits off a private copy so the caller can mutate without affecting other clones.

public func getValue() -> T

Reads the wrapped value out of storage. Returns a copy — the underlying T is borrowed through Pointer.with, so no temporary RcBoxStorage is created or dropped.

public func isUnique() -> Bool

Returns true when no other clone is sharing storage. The litmus test for "safe to mutate in place" in COW collections.

public func modify[R]((T) -> R) -> R

Mutates the wrapped value in place, passing it to body as a mutating argument. No clone or write-back — body mutates the heap value directly. Safe only when this is the unique owner (isUnique() == true); COW types check that first (see CowBox.modify).

public func pointeeRef() -> &T

public func refCount() -> Int64

Current strong reference count. Mostly useful for tests and diagnostics; production COW logic should branch on isUnique.

public func setValue(consuming T)

Overwrites the wrapped value in place. Safe only when this is the unique owner (isUnique() == true); otherwise other clones see the new value, defeating COW. The COW types check isUnique before calling this and deepClone otherwise. Takes value by consuming — the caller's copy is dead after this.

public func valuePtr() -> Pointer[T]

Returns a pointer to the wrapped value on the heap. The pointer is valid as long as the RcBox (and its storage) is alive. Use this to read individual fields without creating a full T clone whose deinit would free owned resources prematurely.

ImplementsCloneable

Methods

public func clone() -> RcBox[T]

Bumps the refcount and returns a second RcBox pointing at the same storage. The receiver and the returned box now both reference the value; the next mutation should test isUnique.

ImplementsMutableIndirection

Methods

public mutating func pointeeMutRef() -> &mutating T

Defined in lang/std/memory/rcbox.ks