Pointer.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/common/macro/Macros.h"
#include "bio/common/type/EnableIf.h"
#include "bio/common/type/IsMemcpySafe.h"
#include "bio/common/type/IsPointer.h"
#include "bio/common/type/RemovePointer.h"
#include "bio/common/wrapper/PointerArena.h"
#include "bio/common/wrapper/PointerSafety.h"
 
#ifndef NULL
    #include <cstddef>
#endif
 
//@formatter:off
#if BIO_CPP_VERSION >= 11
    #include <type_traits>
#endif
#include <functional>
//@formatter:on
 
namespace bio {
 
namespace pointer_detail {
 
template < typename FROM, typename TO >
struct IsPointerConvertible
{
private:
    struct Yes { char mPad[1]; };
    struct No { char mPad[2]; };
    static Yes Test(TO*);
    static No Test(...);
    // A FROM* value to feed the overload set. Never evaluated (sizeof context).
    static FROM* MakeFrom();
public:
    static const bool sValue = (sizeof(Test(MakeFrom())) == sizeof(Yes));
};
 
} //pointer_detail namespace
 
template < typename T >
class Pointer
{
public:
    typedef T Type;
 
    Pointer()
        :
        //@formatter:off
        #if BIO_COMPACT_POINTER_STORAGE
        mHandle(0)
        #else
        mRaw(NULL)
        #endif
        //@formatter:on
    {
    }
 
    Pointer(T* raw)
        :
        //@formatter:off
        #if BIO_COMPACT_POINTER_STORAGE
        mHandle(::bio::pointer_arena::HandleFor(raw))
        #else
        mRaw(raw)
        #endif
        //@formatter:on
    {
    }
 
    template < typename U >
    Pointer(
        const Pointer< U >& other,
        typename type::EnableIf<
            pointer_detail::IsPointerConvertible< U, T >::sValue,
            int
        >::Type = 0
    )
        :
        //@formatter:off
        #if BIO_COMPACT_POINTER_STORAGE
        mHandle(::bio::pointer_arena::HandleFor(static_cast< T* >(other.Get())))
        #else
        mRaw(other.Get())
        #endif
        //@formatter:on
    {
    }
 
    // Copy ctor, copy assignment and dtor are intentionally left implicit
    // (compiler-defaulted): a single T* member makes them a trivial bit-copy /
    // no-op, which is what keeps Pointer< T > trivially-copyable and exactly the
    // size/behavior of a raw T*. Declaring them would risk making the type
    // non-trivial; do not.
 
    Pointer& operator=(T* raw)
    {
        //@formatter:off
        #if BIO_COMPACT_POINTER_STORAGE
        mHandle = ::bio::pointer_arena::HandleFor(raw);
        #else
        mRaw = raw;
        #endif
        //@formatter:on
        return *this;
    }
 
    template < typename U >
    typename type::EnableIf<
        pointer_detail::IsPointerConvertible< U, T >::sValue,
        Pointer&
    >::Type operator=(const Pointer< U >& other)
    {
        //@formatter:off
        #if BIO_COMPACT_POINTER_STORAGE
        mHandle = ::bio::pointer_arena::HandleFor(static_cast< T* >(other.Get()));
        #else
        mRaw = other.Get();
        #endif
        //@formatter:on
        return *this;
    }
 
    operator T*() const
    {
        return Get();
    }
 
    T* operator->() const
    {
        T* raw = Get();
        ::bio::pointer_safety::AssertLive< T >(raw, __FILE__, __LINE__);
        return raw;
    }
 
    T& operator*() const
    {
        T* raw = Get();
        ::bio::pointer_safety::AssertLive< T >(raw, __FILE__, __LINE__);
        return *raw;
    }
 
    T* Get() const
    {
        //@formatter:off
        #if BIO_COMPACT_POINTER_STORAGE
        return static_cast< T* >(const_cast< void* >(::bio::pointer_arena::ResolveFast(mHandle)));
        #else
        return mRaw;
        #endif
        //@formatter:on
    }
 
    //@formatter:off
    #if BIO_COMPACT_POINTER_STORAGE
    ::bio::pointer_arena::Handle GetHandle() const
    {
        return mHandle;
    }
    #endif
    //@formatter:on
 
    //@formatter:off
    #if BIO_CPP_VERSION >= 11
    explicit operator bool() const
    {
        return Get() != NULL;
    }
    #endif
    //@formatter:on
 
    bool operator==(const Pointer& other) const
    {
        return Get() == other.Get();
    }
 
    template < typename U >
    bool operator==(const Pointer< U >& other) const
    {
        return Get() == other.Get();
    }
 
    bool operator!=(const Pointer& other) const
    {
        return Get() != other.Get();
    }
 
    template < typename U >
    bool operator!=(const Pointer< U >& other) const
    {
        return Get() != other.Get();
    }
 
    bool operator==(T* raw) const
    {
        return Get() == raw;
    }
 
    bool operator!=(T* raw) const
    {
        return Get() != raw;
    }
 
    bool operator<(const Pointer& other) const
    {
        return ::std::less< T* >()(Get(), other.Get());
    }
 
private:
    //@formatter:off
    #if BIO_COMPACT_POINTER_STORAGE
    ::bio::pointer_arena::Handle mHandle;
    #else
    T* mRaw;
    #endif
    //@formatter:on
};
 
//@formatter:off
 
template < typename T >
inline bool operator==(T* raw, const Pointer< T >& wrapped)
{
    return wrapped == raw;
}
 
template < typename T >
inline bool operator!=(T* raw, const Pointer< T >& wrapped)
{
    return wrapped != raw;
}
 
template < typename T >
inline void Delete(Pointer< T > wrapped)
{
    delete wrapped.Get();
}
 
// NOTE: no dedicated std::nullptr_t comparison overloads. `p == nullptr`,
// `nullptr != p`, `p == NULL`, `p == 0` all resolve via the T* comparisons
// above (each null constant converts to T*), exactly as for a raw pointer —
// verified at build time across cpp98..cpp20. Adding nullptr_t overloads only
// widens the surface with no behavioral gain.
 
//@formatter:on
 
//@formatter:off
#if BIO_CPP_VERSION >= 11
    // PHASE-0 layout contract. Normal builds keep Pointer< T > byte-for-byte
    // compatible with raw T*. The level-2 compact-pointer path is a source-only
    // feasibility mode that swaps the storage to a 32-bit process-global handle.
    // NB: assert on a COMPLETE pointee (int / double), never Pointer< void >:
    // instantiating Pointer< void > would form the ill-formed `void& operator*()`
    // return type in its signature. All object pointers are the same width, so
    // sizeof(int*) == sizeof(void*) and the guarantee is fully covered.
    #if BIO_COMPACT_POINTER_STORAGE
    static_assert(
        sizeof(Pointer< int >) == sizeof(uint32_t),
        "compact Pointer< T > must be exactly one 32-bit handle wide.");
    static_assert(
        sizeof(Pointer< double >) == sizeof(uint32_t),
        "compact Pointer< T > must be exactly one 32-bit handle wide.");
    #else
    static_assert(
        sizeof(Pointer< int >) == sizeof(int*),
        "Pointer< T > must be exactly one pointer wide (raw-pointer drop-in).");
    static_assert(
        sizeof(Pointer< double >) == sizeof(void*),
        "Pointer< T > must be exactly one pointer wide (raw-pointer drop-in).");
    #endif
    static_assert(
        ::std::is_standard_layout< Pointer< int > >::value,
        "Pointer< T > must be standard-layout (raw-pointer drop-in).");
    static_assert(
        ::std::is_trivially_copyable< Pointer< int > >::value,
        "Pointer< T > must be trivially-copyable / trivially-relocatable.");
#endif
//@formatter:on
 
namespace type {
 
template < typename T >
struct IsMemcpySafeImplementation< Pointer< T > >
{
    static const bool sValue = true;
};
 
template < typename T >
struct IsPointerImplementation< Pointer< T > >
{
    static const bool sValue = true;
};
 
template < typename T >
struct RemovePointer< Pointer< T > >
{
    typedef T Type;
};
 
template < typename T >
struct IsPointerWrapper< Pointer< T > >
{
    static const bool sValue = true;
};
 
} //type namespace
 
} //bio namespace