CowPtr.h

Go to the documentation of this file.

/*
 * This file is a part of the Biology project by eons LLC.
 * Biology (aka Develop Biology) is a framework for approaching software
 * development from a natural sciences perspective.
 *
 * Copyright (C) 2026 Séon O'Shannon & eons LLC
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#pragma once
 
#include "bio/chemical/wrapper/CowControlBlock.h"
#include "bio/common/wrapper/PointerArena.h"
 
#ifndef NULL
    #include <cstddef>
#endif
 
#include <cassert>
#include <stdint.h> // uintptr_t — for the tagged borrowed-reference encoding (cpp98-safe)
 
namespace bio {
 
template < typename T >
class CowPtr
{
public:
    typedef T Type;
 
    CowPtr()
        :
        mSlot(NULL)
    {
    }
 
    explicit CowPtr(
        T* owned,
        bool immutable = false
    )
        :
        mSlot(owned ? new CowControlBlock< T >(owned, immutable) : NULL)
    {
    }
 
    static CowPtr Borrow(T* borrowed)
    {
        CowPtr result;
        if (borrowed)
        {
            assert(!(reinterpret_cast< uintptr_t >(borrowed) & TAG)
                && "CowPtr::Borrow() requires a 2-byte-aligned payload");
            result.mSlot = reinterpret_cast< CowControlBlock< T >* >(
                reinterpret_cast< uintptr_t >(borrowed) | TAG);
        }
        return result;
    }
 
    bool IsBorrowed() const
    {
        return IsBorrowedSlot(mSlot);
    }
 
    CowPtr(const CowPtr& other)
        :
        mSlot(other.mSlot)
    {
        if (mSlot && !IsBorrowedSlot(mSlot))
        {
            CowInc(mSlot->mRefCount);
        }
    }
 
    CowPtr& operator=(const CowPtr& other)
    {
        if (mSlot != other.mSlot)
        {
            CowControlBlock< T >* old = mSlot;
            mSlot = other.mSlot;
            if (mSlot && !IsBorrowedSlot(mSlot))
            {
                CowInc(mSlot->mRefCount);
            }
            if (old && !IsBorrowedSlot(old))
            {
                Release(old);
            }
        }
        return *this;
    }
 
    ~CowPtr()
    {
        if (mSlot && !IsBorrowedSlot(mSlot))
        {
            Release(mSlot);
        }
    }
 
    const T* View() const
    {
        if (!mSlot)
        {
            return NULL;
        }
        if (IsBorrowedSlot(mSlot))
        {
            return BorrowedPayload(mSlot);
        }
        return mSlot->mPayload;
    }
 
    bool IsShared() const
    {
        return mSlot && !IsBorrowedSlot(mSlot) && CowLoad(mSlot->mRefCount) > 1;
    }
 
    bool IsNull() const
    {
        return !mSlot;
    }
 
    template < typename CLONE >
    T* Moo(CLONE cloneFn)
    {
        if (!mSlot)
        {
            return NULL;
        }
        if (IsBorrowedSlot(mSlot))
        {
            return BorrowedPayload(mSlot);
        }
        if (mSlot->mImmutable || CowLoad(mSlot->mRefCount) > 1)
        {
            T* fresh = cloneFn(mSlot->mPayload); // one deep copy at the leaf type
            CowControlBlock< T >* old = mSlot;
            mSlot = new CowControlBlock< T >(fresh, false); // private, refcount 1
            Release(old); // old was >1 or an (un-freed) prototype: never frees a live share
        }
        return mSlot->mPayload;
    }
 
    T* Mutable()
    {
        if (IsBorrowedSlot(mSlot))
        {
            return BorrowedPayload(mSlot);
        }
        assert(!IsShared() && "CowPtr::Mutable() on a shared payload — use Moo(cloner)");
        return mSlot ? mSlot->mPayload : NULL;
    }
 
    void Reset(T* owned)
    {
        if (mSlot && !IsBorrowedSlot(mSlot))
        {
            Release(mSlot);
        }
        mSlot = owned ? new CowControlBlock< T >(owned, false) : NULL;
    }
 
private:
    // The low-bit tag marking a borrowed (block-less) slot. Free because heap blocks
    // and heap payloads are >= 2-byte aligned.
    static const uintptr_t TAG = 1;
 
    // mSlot is either a CowControlBlock< T >* (owned, low bit clear) or a tagged T*
    // (borrowed, low bit set), or NULL.
    CowControlBlock< T >* mSlot;
 
    static bool IsBorrowedSlot(CowControlBlock< T >* slot)
    {
        return (reinterpret_cast< uintptr_t >(slot) & TAG) != 0;
    }
 
    static T* BorrowedPayload(CowControlBlock< T >* slot)
    {
        return reinterpret_cast< T* >(reinterpret_cast< uintptr_t >(slot) & ~TAG);
    }
 
    static void Release(CowControlBlock< T >* block)
    {
        if (CowDecAndIsLast(block->mRefCount))
        {
            if (!block->mImmutable)
            {
                //@formatter:off
                #if BIO_COMPACT_POINTER_STORAGE
                if (::bio::pointer_arena::Owns(block->mPayload))
                {
                    ::bio::pointer_arena::Delete(block->mPayload);
                }
                else
                {
                    delete block->mPayload;
                }
                #else
                delete block->mPayload;
                #endif
                //@formatter:on
                delete block;
            }
            // Immutable prototypes are process-lifetime: intentionally never freed.
        }
    }
};
 
} // namespace bio