Core and memory

enum class ToggleCategory : uint8_t

Lifecycle category of a toggle (Fowler’s feature-flag categories).

The category enforces nothing by itself; it records the expected lifetime so a lint or test can flag, for example, a release toggle that outlived its feature. Ops and UI settings are long-lived; a release toggle is removed once its feature lands.

Values:

enumerator Release

enumerator Ops

enumerator Experiment

enum Type

Data type tag for a dynamic toggle value.

Values:

enumerator TYPE_NONE

enumerator TYPE_BOOL

enumerator TYPE_INT8

enumerator TYPE_INT16

enumerator TYPE_INT32

enumerator TYPE_INT64

enumerator TYPE_REAL

enumerator TYPE_STRING

enumerator TYPE_SUBKEY

template<typename I, typename R>
class NumberBase

#include <base.hpp>

Fixes the integer and real value types for spatial data structures.

Template Parameters:

• I – Integral index type.

• R – Floating-point real type.

Subclassed by solvcon::SpaceBase< ND, int32_t, double >, solvcon::SpaceBase< ND, I, R >

template<uint8_t ND, typename I, typename R>
class SpaceBase : public solvcon::NumberBase<I, R>

#include <base.hpp>

Spatial table basic information.

Any table-based data store for spatial data should inherit this class template.

class Formatter

#include <base.hpp>

Deprecated ostringstream-based string builder; prefer std::format.

Streams values with operator<< and yields the accumulated text through str() or an implicit std::string conversion. Taken from https://stackoverflow.com/a/12262626 .

class ConcreteBuffer : public std::enable_shared_from_this<ConcreteBuffer>, public solvcon::BufferBase<ConcreteBuffer>

#include <ConcreteBuffer.hpp>

Untyped and unresizeable memory buffer for contiguous data storage.

Public Functions

inline ConcreteBuffer(size_t nbytes, size_t alignment, const ctor_passkey&)

Parameters:

• nbytes – [in] Size of the memory buffer in bytes.

• alignment – [in] Alignment for the memory buffer in bytes. 0 means no alignment. Valid values are 0, 16, 32, or 64.

inline ConcreteBuffer(size_t nbytes, int8_t *data, std::unique_ptr<remover_type> &&remover, size_t alignment, const ctor_passkey&)

Parameters:

• nbytes – [in] Size of the memory buffer in bytes.

• data – [in] Pointer to the memory buffer that is not supposed to be owned by this ConcreteBuffer.

• remover – [in] The memory deallocator for the unowned data buffer passed in.

• alignment – [in] Alignment for the memory buffer in bytes. 0 means no alignment. Valid values are 0, 16, 32, or 64.

Public Static Functions

static inline std::shared_ptr<ConcreteBuffer> construct()

Construct an empty ConcreteBuffer with no data and no alignment.

template<typename T>
class SimpleArray : public solvcon::detail::SimpleArrayMixinModifiers<SimpleArray<T>, T>, public solvcon::detail::SimpleArrayMixinSum<SimpleArray<T>, T>, public solvcon::detail::SimpleArrayMixinCalculators<SimpleArray<T>, T>, public solvcon::detail::SimpleArrayMixinSort<SimpleArray<T>, T>, public solvcon::detail::SimpleArrayMixinSearch<SimpleArray<T>, T>, public solvcon::detail::SimpleArrayMixinMatrix<SimpleArray<T>, T>

#include <SimpleArray.hpp>

Simple array type for contiguous memory storage.

Size does not change. The copy semantics performs data copy. The move semantics invalidates the existing memory buffer.

Public Functions

inline explicit SimpleArray(size_t length, size_t alignment = 0)

Constructor with length and optional alignment.

Parameters:

• length – the length of the array in items

• alignment – the memory alignment in bytes (default: 0, no special alignment, and valid values are 16, 32, and 64)

inline size_t size() const noexcept

In the following numpy documentaions, size() are calculated based on the number of the elements.

https://numpy.org/doc/2.2/reference/generated/numpy.ndarray.size.html SimpleArray matchs the behavior of numpy.ndarray.

inline size_t alignment() const noexcept

Return the underlying buffer alignment in bytes. If no buffer or no alignment, return 0.

void transpose(bool copy = false)

Transpose by reversing all axes in place.

Parameters:

copy – When false (default), perform a view-only flip. When true, replace the buffer with a freshly allocated C-contiguous one holding the physically transposed contents.

void transpose(shape_type const &axis, bool copy = false)

Transpose with axes permuted by the given index vector in place.

Parameters:

• axis – Permutation: the i-th new axis is sourced from the axis[i]-th old axis. Must be a valid permutation of [0, ndim).

• copy – When false (default), perform a view-only permutation of the metadata. When true, physically permute contents into a freshly allocated C-contiguous buffer.

SimpleArray transpose_copy() const

Transpose with a fresh C-contiguous array returned.

The column-major byte layout against the original shape is structurally identical to the C-contiguous byte layout of a transposed array.

Returns:

Freshly allocated C-contiguous SimpleArray with reversed axes.

SimpleArray to_row_major() const

Return a fresh C-contiguous (row-major) array with the same logical shape and values as *this.

Clones the buffer when the source is already C-contiguous; otherwise allocates a fresh buffer and copies element-wise.

Returns:

Freshly allocated C-contiguous SimpleArray.

SimpleArray to_column_major() const

Return a fresh F-contiguous (column-major) array with the same logical shape and values as *this.

Clones the buffer when the source is already F-contiguous; otherwise allocates a fresh buffer with F-contiguous strides and copies element-wise.

Returns:

Freshly allocated F-contiguous SimpleArray.

class DataType

#include <SimpleArray.hpp>

Runtime element-type tag mirroring the scalar types a SimpleArray supports.

Covers bool, the signed and unsigned 8- to 64-bit integers, the 32- and 64-bit floats, and the 64- and 128-bit complex types. Converts to and from its enum and a type string, and DataType::from<T>() maps a C++ type to its tag.

class SimpleArrayPlex

#include <SimpleArray.hpp>

Type-erased SimpleArray pairing a buffer and shape with a runtime DataType.

Holds an array of any supported element type behind one handle, dispatching on the DataType, so code generic over the element type can store and pass arrays uniformly.

Public Functions

inline const void *instance_ptr() const

Get the pointer to the const instance of SimpleArray<T>.

inline void *mutable_instance_ptr() const

Get the pointer to the mutable instance of SimpleArray<T>.

template<typename T>
class SimpleCollector

#include <SimpleCollector.hpp>

Growable typed buffer that collects elements of type T contiguously.

Backs storage with a BufferExpander, grows as elements are appended, and hands the result to a SimpleArray without copying. Prefer it over a std::vector when the data must become a SimpleArray.

Template Parameters:

T – Element value type.

template<typename T, size_t N = 3>
class small_vector

#include <small_vector.hpp>

Vector with small-buffer optimization.

Stores up to N elements inline and moves to a heap allocation only when the size exceeds N, avoiding allocation for the common short case.

Template Parameters:

• T – Element value type.

• N – Inline capacity before the first heap allocation.

Public Functions

iterator partition(iterator left, iterator right, iterator pivot)

Partition function using lomuto_branchless_cyclic_opt algorithm.

This implementation optimizes the partition step to reduce branch misses and cache misses.

Reference: https://github.com/Voultapher/sort-research-rs/blob/main/writeup/lomcyc_partition/text.md

class MetalManager

#include <metal.hpp>

Process-wide owner of the single Metal device handle.

The instance is created on first access and acquires the Metal device in startup(); shutdown() releases it. Copy and move are deleted so the device has exactly one owner.

template<typename T>
struct is_complex : public std::false_type

#include <Complex.hpp>

Type trait that reports whether a type is a solvcon Complex.

The primary template inherits std::false_type; the specialization for Complex<T> inherits std::true_type.

template<typename T>
struct is_real : public std::is_floating_point<T>

#include <Complex.hpp>

Type trait that reports whether a type is a real floating-point type.

class StopWatch

#include <profile.hpp>

Simple timer for wall time using high-resolution clock.

Public Functions

inline double lap()

Return seconds between laps.

inline double duration() const

Return seconds between end and start.

Public Static Functions

static inline StopWatch &me()

A singleton.

static inline constexpr double resolution()

Return resolution in second.

template<typename T>
class RadixTreeNode

#include <RadixTree.hpp>

A node in a RadixTree.

Each node owns a signed integer key, a name, a value of type T, a list of owned child nodes, and a back pointer to its parent.

template<typename T>
class RadixTree

#include <RadixTree.hpp>

A radix tree that maps names to stable integer ids.

Each distinct name receives a unique signed integer id, and a current node pointer walks down the tree as named entries are visited. A stable snapshot of the id map supports re-entrant-safe reads.

struct CallerProfile

#include <RadixTree.hpp>

The profiling result of one caller.

It records the stopwatch start time, the total elapsed time in nanoseconds, the call count, and stable snapshots of the total time and call count for re-entrant-safe reads.

Public Members

std::chrono::nanoseconds stable_total_time = std::chrono::nanoseconds(0)

use nanoseconds to have higher precision

class CallProfiler

#include <RadixTree.hpp>

The profiler that profiles the hierarchical caller stack.

Public Functions

void start_caller(const std::string &caller_name, const std::function<void()> &cancel_callback)

Called when a function starts.

void end_caller()

Called when a function ends.

inline void print_profiling_result(std::ostream &outstream) const

Print the profiling information.

void reset()

Reset the profiler.

inline void cancel()

Cancel the profiling from all probes.

Public Static Functions

static inline CallProfiler &instance()

A singleton.

class CallProfilerProbe

#include <RadixTree.hpp>

Utility to profile a call.

class SerializableRadixTreeNode : public solvcon::SerializableItem

#include <SerializableProfiler.hpp>

Serializable snapshot of one call profiler radix tree node.

It captures the node key, name, accumulated total time (nanoseconds), and call count, plus the child nodes whose stable call count is positive. The running flag and start time are intentionally omitted because they carry no meaning after deserialization.

class SerializableRadixTree : public solvcon::SerializableItem

#include <SerializableProfiler.hpp>

Serializable snapshot of a whole call profiler radix tree.

It holds the root node, the name-to-key identifier map, and the next unique node identifier, mirroring the stable state of a RadixTree<CallerProfile>.

class CallProfilerSerializer

#include <SerializableProfiler.hpp>

Utility to serialize and deserialize CallProfiler.

class SerializableItem

#include <SerializableItem.hpp>

Abstract interface for objects that serialize to and from JSON.

Subclassed by solvcon::SerializableRadixTree, solvcon::SerializableRadixTreeNode, solvcon::WorldDegeneracy, solvcon::WorldDiagnostics, solvcon::WorldIntersection, solvcon::WorldShapeState, solvcon::WorldState

template<typename T>
struct ToggleRegister

#include <toggle.hpp>

A single stored toggle value.

Named after the atomic register of shared-memory theory: a single-value shared location. A scalar register holds a std::atomic so its read and write are lock-free and never torn; get and set use memory_order_relaxed because a toggle publishes nothing but itself.

template<>
struct ToggleRegister<std::string>

#include <toggle.hpp>

String register.

A string is not a hot-path value: it is read by the UI and config code only, never in a tight loop, so it is a plain std::string guarded by the table mutex rather than an atomic. get returns a reference that is valid only while no writer mutates the same key.

template<typename T>
class ToggleRegisterColumn

#include <toggle.hpp>

Column of ToggleRegister<T> with stable register addresses.

Each register is heap-owned through a unique_ptr, so a register keeps its address for its lifetime even as the column grows, and a resolved handle stays valid. The heap box also lets a non-movable atomic register live in a standard container. Indices are dense and start at zero, matching the offsets held by DynamicToggleIndex.

struct DynamicToggleIndex

#include <toggle.hpp>

Index and type tag that locates a dynamic toggle value in its typed storage vector.

The bool conversion is true when the type is not TYPE_NONE, and index is a 32-bit offset into the storage vector for the given Type.

template<typename T>
struct ToggleTypeTraits

Maps a C++ value type to its DynamicToggleIndex type tag.

The primary template is left undefined so an unsupported type is a compile error rather than a silent mismatch.

class ToggleSubscription

#include <toggle.hpp>

RAII handle for one change subscription.

Dropping it unsubscribes, so a callback never outlives the widget it belongs to. It is move-only and tolerates the table being destroyed first (the weak reference simply expires).

class HierarchicalToggleAccess

#include <toggle.hpp>

Hierarchical accessor that reads and writes a DynamicToggleTable through dotted keys.

It holds a base prefix and joins it to a key with a “.” separator (see rekey), so nested subkeys can be reached without repeating the full path.

class DynamicToggleTable

#include <toggle.hpp>

Runtime table of dynamic toggles keyed by name.

Each key maps to a DynamicToggleIndex that selects one of the per-type storage vectors (bool, int8, int16, int32, int64, real, and string). Values can be added, read, written, and cleared during runtime.

Public Functions

inline uint64_t generation() const

Monotonic stamp bumped on every clear.

A handle resolved before a clear carries the old generation, so it can be detected as stale rather than aliasing a register reused after the clear.

template<typename T>
ToggleRef<T> declare(std::string const &key, T const &default_value, ToggleCategory category = ToggleCategory::Ops)

Create a toggle with a default and a category, and return a handle.

Re-declaring an existing key of the same type is idempotent and returns a handle to the existing register. A conflicting type is an error.

inline ToggleCategory category(std::string const &key) const

The category recorded for a key, or Ops if the key was never declared.

template<typename T>
ToggleRef<T> ref(std::string const &key)

Resolve an existing key to a handle; an invalid handle if it is missing or has a different type.

template<typename T>
T get(std::string const &key, T const &default_value) const

Typed read returning the caller default on a missing or wrong-typed key (the OpenFeature contract).

template<typename T>
T at(std::string const &key) const

Strict typed read that throws on a missing or wrong-typed key.

inline ToggleSubscription on_change(std::string const &key, std::function<void()> callback)

Subscribe to changes of a key.

The callback runs after the write lock is released, so it may call back into the store (including set) without deadlock, and firing outside the lock keeps a Python callback from inverting lock order against the GIL. A no-op write (setting the value already stored) does not fire. Dropping the returned token unsubscribes.

template<typename T>
class ToggleRef

#include <toggle.hpp>

A resolved, typed handle to one toggle register.

It binds a key to its register once (table, index, and the table generation at resolution) so a hot path reads the value without touching the string map again. Because the storage keeps register addresses stable, the bound pointer survives unrelated toggles being added; because the handle stamps the table generation, a handle taken before a dynamic_clear is refused afterward instead of aliasing a reused register.

Public Functions

inline bool valid() const

True when the handle points at a live register in the current generation (not default-constructed and not invalidated by a clear).

class SolidToggle

#include <toggle.hpp>

Compatibility facade for the former compile-time solid toggles.

The one solid toggle, use_pyside, is now an inline constexpr build switch (see build_config.hpp) that the optimizer folds away. This stateless facade keeps the old accessor working until its callers move.

class FixedToggle

#include <toggle.hpp>

Compatibility facade for the former fixed toggles.

python_redirect and show_axis are now ordinary declared toggles in the store, so they gain change notification and serialization. This facade reads and writes them through the store (with their startup defaults), keeping the old get_/set_ accessors working until their callers move.

class Toggle

#include <toggle.hpp>

The toggle system for solvcon.

All toggles now live in one store, the DynamicToggleTable

of typed registers. A toggle is created and named once with declare<T>(key, default,

category); a hot path binds a typed handle (ref<T>) and reads it with a single atomic load; the UI edits it by key and subscribes with on_change.

Two access styles read the same store:

1. Typed evaluation by key: get<T>(key, default) returns the caller default on a missing or wrong-typed key, and at<T>(key) throws. From Python the wrapper infers the type and the hierarchy uses dotted keys or attribute syntax, for example:

   tg.top_level.second_level.key_name = value

2. Hoisted handles: ToggleRef<T> resolves the key once and reads the atomic register with no map lookup, for tight loops.

The former solid and fixed toggles are compatibility facades: use_pyside is an inline constexpr build switch (see build_config.hpp), and python_redirect and show_axis are ordinary declared toggles in the store.

class CommandLineInfo

#include <toggle.hpp>

Captured command-line state for the current process.

It stores the executable basename and the original, populated, and Python argument vectors. Once frozen, set_python_argv is ignored. It also builds the C-style argv buffer used to launch a Python main.

class PopulatePasskey

#include <toggle.hpp>

class ProcessInfo

#include <toggle.hpp>

Process-wide information accessed as a singleton.

It owns the CommandLineInfo for the process and offers helpers to populate the command line and set environment variables.