cbeam::memory::pointer

Overview

pointer is a versatile wrapper for void*, usable inside xpod::type as one of its std::variant data types. It optionally holds a reference-counted buffer or a shared pointer, ensuring that if the memory is managed, the lifetime remains controlled. In simpler cases, it just stores a raw pointer.

Key Goals
1. Provide a pointer type that can be serialized or placed in a variant (xpod::type) without losing lifetime safety.
2. Detect if the pointer is managed by stable_reference_buffer or by a std::shared_ptr to increment reference counts accordingly.
3. Supply a textual representation (“0x...”) for debugging or serialization (e.g., you can construct it from or convert it to a string).

Typical Usage

1. Basic Construction

#include <cbeam/memory/pointer.hpp>

// Raw pointer construction:
int x = 42;
cbeam::memory::pointer p1(&x);

// String-based pointer (parsed to void*):
cbeam::memory::pointer p2("0x7fffd1234567");
  • If the pointer is not recognized as belonging to stable_reference_buffer, it remains a simple raw pointer.

2. Managed by stable_reference_buffer

#include <cbeam/container/stable_reference_buffer.hpp>

// Suppose `buf` is a stable_reference_buffer
cbeam::container::stable_reference_buffer buf(10, sizeof(int));

// Create pointer from the same memory:
cbeam::memory::pointer p3(buf);
// If recognized, `p3` tracks the stable_reference_buffer reference count internally.

Now, p3 is a “managed” pointer. Destroying p3 will decrement the buffer’s reference count.

3. Managed by std::shared_ptr

#include <memory>

struct MyObject {
    int value;
};

std::shared_ptr<MyObject> sptr = std::make_shared<MyObject>();
sptr->value = 2023;

cbeam::memory::pointer p4(sptr);
// 'p4' references the same data. p4.is_managed() == true

The pointer holds an internal reference to the shared pointer, ensuring that as long as p4 lives, the MyObject isn’t freed.

4. Type Conversions and String Output

// Convert pointer to hex string
std::string s = static_cast<std::string>(p4);
std::cout << "Pointer as hex = " << s << "\n";

// Convert pointer to stable_reference_buffer (if managed, else throws)
auto srb = static_cast<cbeam::container::stable_reference_buffer>(p3);
  • operator std::string() returns 0x... format.
  • explicit operator stable_reference_buffer(): If the pointer is indeed referencing a stable buffer, we retrieve that buffer. Otherwise, an exception is thrown.

Motivation

  • Integration with xpod::type: pointer is one of the variant’s data types, letting you store pointer-like references in a flexible container that might also hold integers, strings, etc.
  • Managed vs. Unmanaged: pointer automatically detects if the underlying pointer is part of a stable_reference_buffer or a std::shared_ptr, which is crucial for correct memory lifetime management in advanced scenarios.
  • String Representation: Easy debugging or serialization, as you can read and write pointers in a hex string form.

When to Use

  • Cross-Library: If you’re passing pointers that are part of a stable reference buffer. pointer ensures the reference count is updated or that the raw pointer is stored consistently.
  • xpod-based Data: If you use xpod::type for messages or config structures and need to include pointer references.
  • Mix of Managed and Unmanaged: In some places, you have raw pointers (like function pointers or stack addresses), in others you have heap-allocated references. pointer can unify this into a single type while retaining (when possible) reference counting.

Summary
- stable_reference_buffer and pointer work hand in hand: one manages stable cross-library buffer ownership; the other can reference that memory from a variant or external code.
- A pointer can also hold a std::shared_ptr, bridging advanced or library-specific memory objects into the same consistent representation.
- Together, they address real-world complexities of shared memory, plugin-based systems, and variant-based data passing without forcing every pointer to be raw or forcibly shared.