bio::CowPtr< T > Class Template Reference

#include <CowPtr.h>

Public Types
typedef T	Type

Public Member Functions
	CowPtr ()
	CowPtr (T *owned, bool immutable=false)
bool	IsBorrowed () const
	CowPtr (const CowPtr &other)
CowPtr &	operator= (const CowPtr &other)
	~CowPtr ()
const T *	View () const
bool	IsShared () const
bool	IsNull () const
template<typename CLONE >
T *	Moo (CLONE cloneFn)
T *	Mutable ()
void	Reset (T *owned)

Static Public Member Functions
static CowPtr	Borrow (T *borrowed)

Detailed Description

template<typename T>
class bio::CowPtr< T >

CowPtr stores ONE pointer, mSlot, which is one of three things:

• NULL -> empty.
• a CowControlBlock< T >* (even) -> OWNED: refcounted, copy-on-write, deletes the payload on last release. The mContents/Solute case and owning Bonds.
• a tagged T* (low bit set) -> BORROWED: a non-owning reference with NO heap block at all. Behaves byte-for-byte like the bare T* it replaces — shares by raw copy (no refcount), never detaches, never deletes. The real owner manages lifetime & mutates in place. The borrowed-Bond case (self-bond, Metallic, Manage), which must add zero allocations; also AtomicCow's snapshot of a bonded (no refcount inflation, so detach decisions stay correct). The tag is the low bit, free because both CowControlBlock and any heap T are at least 2-byte aligned. The owning path is byte-identical to the pre-borrowed CowPtr: the only change is an always-false IsBorrowed() branch the optimizer folds away for owners.

Member Typedef Documentation

Type

template<typename T >

typedef T bio::CowPtr< T >::Type

Constructor & Destructor Documentation

CowPtr() [1/3]

template<typename T >

bio::CowPtr< T >::CowPtr ( )

inline

Null / empty (mirrors a lazily-allocated mContents == NULL).

CowPtr() [2/3]

template<typename T >

bio::CowPtr< T >::CowPtr ( T *  owned, bool  immutable = false  )

inlineexplicit

Adopt an owned payload (refcount 1). Pass immutable=true to seed a process-lifetime per-type prototype that always detaches on first write.

Parameters

owned	the payload to own (may be NULL for empty).
immutable	whether this is an immutable shared prototype.

CowPtr() [3/3]

template<typename T >

bio::CowPtr< T >::CowPtr ( const CowPtr< T > &  other )

inline

SHARE on copy (the win): owned bumps the refcount; borrowed copies the raw tagged pointer (no refcount), exactly like copying a bare T*.

~CowPtr()

template<typename T >

bio::CowPtr< T >::~CowPtr ( )

inline

NON-virtual on purpose (see class doc). Drops one reference (owned only).

Member Function Documentation

Borrow()

template<typename T >

static CowPtr bio::CowPtr< T >::Borrow ( T *  borrowed )

inlinestatic

Wrap a NON-owning reference with NO heap block: this shares the payload by raw pointer copy (no refcount), NEVER deletes it and NEVER detaches on write — exactly the semantics of the bare T it replaces. This is the borrowed-Bond case (self-bond, Metallic, Manage): clone-shares the raw reference, zero allocations.

Parameters

borrowed

the non-owned reference (may be NULL for empty).

Returns

a borrowed CowPtr.

IsBorrowed()

template<typename T >

bool bio::CowPtr< T >::IsBorrowed ( ) const

inline

Returns

true iff *this is a non-owning (borrowed) reference.

IsNull()

template<typename T >

bool bio::CowPtr< T >::IsNull ( ) const

inline

Returns

true iff *this owns no payload.

IsShared()

template<typename T >

bool bio::CowPtr< T >::IsShared ( ) const

inline

Returns

true iff the payload is shared by more than one OWNING owner. Borrowed references carry no refcount, so they are never "shared" in the COW sense.

Moo()

template<typename T >

template<typename CLONE >

T * bio::CowPtr< T >::Moo ( CLONE  cloneFn )

inline

Moo() — Make Owned Object. The write path: detach-on-write. If the payload is shared or an immutable prototype, deep-copy it (via cloneFn, which runs at the leaf type) into a fresh private block before returning a mutable, uniquely-owned pointer. The caller MUST hold the host's exclusive lock around this (see class doc / CowRefCount.h). Borrowed references never copy-on-write: the real owner mutates in place and sharers of a borrowed reference intentionally observe each other's writes. (Yes, the cow says Moo when you make it your own. The name is a unique token by design — a one-line regex un-does it if it ever stops sparking joy.)

Template Parameters

CLONE

a callable T* (const T*) that deep-copies the payload.

Parameters

cloneFn

the typed deep-copier.

Returns

a mutable, uniquely-owned payload (NULL if *this is empty).

Mutable()

template<typename T >

T * bio::CowPtr< T >::Mutable ( )

inline

UNIQUE-OWNER mutable access: returns the payload WITHOUT detaching.

For owners that guarantee they never share this payload — e.g. a LinearMotif< X* >, whose pointer content is type-gated OUT of the clone-sharing path (a raw byte share would alias owned pointees and double-free), so its block is always uniquely owned (refcount 1). Such an owner mutates its payload in place with no copy-on-write overhead.

The debug assert documents and enforces the contract: it MUST NOT be called on a shared payload (that would mutate every sharer's view). Use Moo(cloner) instead whenever sharing is possible.

Returns

the mutable payload, or NULL if empty.

operator=()

template<typename T >

CowPtr & bio::CowPtr< T >::operator= ( const CowPtr< T > &  other )

inline

SHARE on assign. inc-new-before-dec-old makes self-assignment safe. Borrowed slots carry no refcount and are never Released.

Reset()

template<typename T >

void bio::CowPtr< T >::Reset ( T *  owned )

inline

First lazy allocation of a unique OWNED payload (NULL -> owned). Drops any prior reference first (owned or borrowed).

Parameters

owned

the payload to own.

View()

template<typename T >

const T * bio::CowPtr< T >::View ( ) const

inline

VIEW (read) path: never detaches, never bumps the refcount. Safe for unlimited concurrent readers of a shared payload.

Returns

the payload (const), or NULL if empty.

---

The documentation for this class was generated from the following file:

• CowPtr.h