jam Module Reference

Exported Modules
module	native

Concepts
concept	jam::visitor
	A visitor for jam's compressed, alignment-preserving heap.
concept	jam::traceable
	T supports tracing after it is complete.Ordinary trace return types are unrestricted; collection uses their effects. A void claim_and_trace(heap::visitor &) const noexcept member takes priority for allocation tracing and may be virtual. Its override must claim the exact complete object before declaring fields or following targets.

Classes
class	jam::units::space< Rep, Ratio >
	A count of storage units; Ratio measures one unit in bytes. Integer arithmetic and conversions terminate on overflow. Floating arithmetic follows its representation. Like chrono, integral destinations accept only lossless unit conversions implicitly; use space_cast, floor, ceil or round otherwise. There is no implicit conversion to an untyped count. More...
struct	std::common_type< jam::units::space< R1, P1 >, jam::units::space< R2, P2 > >
	Common representation and greatest common unit, as for chrono durations. More...
class	jam::root< T >
	A copyable external root, updated during collection.Four-byte slot index; no heap or registration address is stored. The heap must outlive the root and be current for operations and destruction. More...
class	jam::ptr< T >
	A typed heap offset, with no root registration or ownership. More...
class	jam::weak_ptr< T >
	A four-byte weak heap field; tracing updates its slot without retaining its target.Construct from a ptr or root. Collection clears the field when its target is unclaimed; minor collection leaves old targets alone. Use lock() to retain a target across collection. There is no control block or external registration: stack copies expire at collection just like ptr, even if the target survives. The field must be listed in its owner's manifest or trace hook. More...
class	jam::weak_root< T >
	An external weak slot, updated or cleared by collection without retaining its target.Keep it outside the managed heap. The heap must outlive even an expired attached root. Copies share a registration; moves leave the source detached and expired. Four-byte slot index; operations and destruction require the owning heap current. Operations require a quiescent collector. Old targets remain live during minor collection. More...
class	jam::weak< V >
	An external conditional weak-value handle; registration survives dropped handles.Keep this handle outside the managed heap. Copies share one registration. Finalization expires all copies before the callback runs; resurrection does not rearm it. More...
class	jam::heap_scope
	Bind an existing heap, restoring the previous binding on scope exit.The heap must outlive the scope. Scopes nest on one thread and may re-enter a heap. They neither own the heap nor synchronize access to it. More...
struct	jam::leaf< T >
	A value with no outgoing managed references.Specializing tracer<T> by deriving from leaf<T> explicitly suppresses traversal. Heap storage requirements are separate from this reference-free promise. More...
struct	jam::tracer< T >
	Per-value tracing customization; values without a hook or manifest are leaves.An allocation-only claim_and_trace hook does not describe embedded fields. Scalars and ordinary records without a trace member or manifest contain no managed edges by convention. Records containing managed pointers must enumerate them in a manifest, trace member or tracer specialization. Trivial copyability does not enumerate fields. More...
struct	jam::tracer< T >
	Forward a value hook or a cooperative allocation hook.Visit each live ptr by reference from the supplied value. Nested values share the enclosing allocation's pointer mask. Static trace(visit, ptr<T>) owns allocation claiming and may walk directly between records. More...
struct	jam::tracer< ptr< T > >
	Tag a reference slot and enqueue its target. More...
struct	jam::tracer< weak_ptr< T > >
	Declare a weak field for forwarding without following its target. More...
struct	jam::tracer< std::tuple< Ts... > >
	Visit each tuple element in the enclosing allocation. More...
struct	jam::tracer< std::array< T, N > >
	Visit each array element in the enclosing allocation. More...
struct	jam::tracer< std::variant< Ts... > >
	Visit only the active variant alternative in the enclosing allocation. More...
struct	jam::generation_options
	Sizing policy for one generation. Sizes are platform pages. More...
struct	jam::heap_options
	Two generations and one shared worker pool. More...
class	jam::heap
	A circular, double-mapped arena with bounded parallel compaction.Compressed four-byte offsets address two generations of up to 16 GiB each. The high bit selects young; the remaining bits count eight-byte cells. Record alignment up to 64 bytes is retained by dilation and padding between independent rank blocks. Allocation and liveness always use eight-byte cells. Clients trace complete byte-relocatable records; the heap does not infer boundaries or run destructors. This storage contract extends beyond ISO C++ trivial-copy guarantees: moving representation bytes must preserve meaning after ptr fields are forwarded. Raw address-dependent state and required destruction are unsupported. Multiple markers may trace a frozen heap. Join them before compaction, mutation, allocation, or inspecting metadata. Borrows expire on movement. More...
struct	jam::tracer< native::simd< ptr< T >, N, A > >
	Trace actual pointer lanes, including null fields, in register order. More...
struct	jam::tracer< native::wide< V, K > >
	Trace each register's fields in the enclosing allocation. More...

Typedefs
using	jam::units::kibi = std::ratio<1024>
	Binary kilo: 1024.
using	jam::units::mebi = std::ratio<1048576>
	Binary mega: 1024 squared.
using	jam::units::gibi = std::ratio<1073741824>
	Binary giga: 1024 cubed.
using	jam::units::bytes = space<std::size_t>
	Whole bytes.
using	jam::units::kilobytes = space<std::size_t, std::kilo>
	Thousands of bytes.
using	jam::units::megabytes = space<std::size_t, std::mega>
	Millions of bytes.
using	jam::units::gigabytes = space<std::size_t, std::giga>
	Billions of bytes.
using	jam::units::kibibytes = space<std::size_t, kibi>
	Groups of 1024 bytes.
using	jam::units::mebibytes = space<std::size_t, mebi>
	Groups of 1048576 bytes.
using	jam::units::gibibytes = space<std::size_t, gibi>
	Groups of 1073741824 bytes.
using	jam::units::pages = space<std::size_t, std::ratio<JAM_PAGE_BYTES>>
	Platform pages, fixed at build time.

Functions
template<class To, class R, class P>
constexpr To	jam::units::space_cast (space< R, P > value) noexcept
	Explicit conversion; fractional integral ticks truncate toward zero.
template<class R1, class P1, class R2, class P2>
constexpr auto	jam::units::operator<=> (space< R1, P1 > a, space< R2, P2 > b) noexcept
	Compare amounts without overflowing an integral common-unit conversion.
template<class R1, class P1, class R2, class P2>
constexpr bool	jam::units::operator== (space< R1, P1 > a, space< R2, P2 > b) noexcept
	Equal amounts may have different units or representations.
template<class R1, class P1, class R2, class P2>
constexpr auto	jam::units::operator+ (space< R1, P1 > a, space< R2, P2 > b) noexcept
	Add amounts in their common unit.
template<class R1, class P1, class R2, class P2>
constexpr auto	jam::units::operator- (space< R1, P1 > a, space< R2, P2 > b) noexcept
	Subtract amounts in their common unit.
template<class R, class P, class S> requires std::is_arithmetic_v<S>
constexpr auto	jam::units::operator* (space< R, P > a, S b) noexcept
	Multiply an amount by a scalar, preserving its unit.
template<class R, class P, class S> requires std::is_arithmetic_v<S>
constexpr auto	jam::units::operator* (S a, space< R, P > b) noexcept
	Multiply a scalar by an amount.
template<class R, class P, class S> requires std::is_arithmetic_v<S>
constexpr auto	jam::units::operator/ (space< R, P > a, S b) noexcept
	Divide an amount by a scalar, preserving its unit.
template<class R1, class P1, class R2, class P2>
constexpr auto	jam::units::operator/ (space< R1, P1 > a, space< R2, P2 > b) noexcept
	Divide two amounts, producing a dimensionless count.
template<std::integral R, class P, std::integral S>
constexpr auto	jam::units::operator% (space< R, P > a, S b) noexcept
	Integral remainder in the original unit.
template<std::integral R1, class P1, std::integral R2, class P2>
constexpr auto	jam::units::operator% (space< R1, P1 > a, space< R2, P2 > b) noexcept
	Integral remainder in the common unit.
template<class To, class R, class P>
constexpr To	jam::units::floor (space< R, P > value) noexcept
	Greatest whole destination count not exceeding the source.
template<class To, class R, class P>
constexpr To	jam::units::ceil (space< R, P > value) noexcept
	Least whole destination count not less than the source.
template<class To, class R, class P> requires std::integral<typename To::rep>
constexpr To	jam::units::round (space< R, P > value) noexcept
	Nearest integral destination count; ties round to even.
template<class R, class P> requires std::is_signed_v<R>
constexpr auto	jam::units::abs (space< R, P > value) noexcept
	Absolute value of a signed amount.
consteval units::bytes	jam::literals::operator""_B (unsigned long long n) noexcept
	Bytes.
consteval units::space< long double, std::ratio< 1 > >	jam::literals::operator""_B (long double n) noexcept
	Fractional B count.
consteval units::kilobytes	jam::literals::operator""_kB (unsigned long long n) noexcept
	Kilobytes.
consteval units::space< long double, std::kilo >	jam::literals::operator""_kB (long double n) noexcept
	Fractional kB count.
consteval units::megabytes	jam::literals::operator""_MB (unsigned long long n) noexcept
	Megabytes.
consteval units::space< long double, std::mega >	jam::literals::operator""_MB (long double n) noexcept
	Fractional MB count.
consteval units::gigabytes	jam::literals::operator""_GB (unsigned long long n) noexcept
	Gigabytes.
consteval units::space< long double, std::giga >	jam::literals::operator""_GB (long double n) noexcept
	Fractional GB count.
consteval units::kibibytes	jam::literals::operator""_KiB (unsigned long long n) noexcept
	Kibibytes.
consteval units::space< long double, units::kibi >	jam::literals::operator""_KiB (long double n) noexcept
	Fractional KiB count.
consteval units::mebibytes	jam::literals::operator""_MiB (unsigned long long n) noexcept
	Mebibytes.
consteval units::space< long double, units::mebi >	jam::literals::operator""_MiB (long double n) noexcept
	Fractional MiB count.
consteval units::gibibytes	jam::literals::operator""_GiB (unsigned long long n) noexcept
	Gibibytes.
consteval units::space< long double, units::gibi >	jam::literals::operator""_GiB (long double n) noexcept
	Fractional GiB count.
template<class T, class... Members> requires (std::is_object_v<Members> && ...)
consteval auto	jam::make_manifest (Members T::*... members)
	Describe the pointer-bearing members of T, including embedded values.T may still be incomplete. List pointers and embedded values that contain pointers; unlisted fields are data. Hooks take precedence over the manifest.
template<class T>
	jam::weak_ptr (ptr< T > const &) -> weak_ptr< T >
	Deduce the target type from a strong pointer.
template<class T>
	jam::weak_ptr (root< T > const &) -> weak_ptr< T >
	Deduce the target type from a root.
template<traceable K, traceable V, traceable F>
weak< V >	jam::mk_weak (ptr< K > const &key, ptr< V > const &value, ptr< F > const &finalizer, std::type_identity_t< void(*)(F *) noexcept > runner) noexcept
	Register a weak key/value pair and managed finalizer in the current heap. The captureless runner receives a nullable F* and obeys normal borrow rules; no destructor is invoked.
template<traceable T, class... Args>
ptr< T >	jam::mk (Args &&... args) noexcept
	Allocate a record in the current heap; register a root before collection.
template<class T, std::size_t N>
constexpr void	jam::unsafe_assign (std::array< ptr< T >, N > &target, std::array< ptr< T >, N > const &source) noexcept
	Bulk-copy pointer bits without registration; the caller owns the barrier.
template<class T, std::size_t N>
constexpr void	jam::assign (std::array< ptr< T >, N > &target, std::array< ptr< T >, N > const &source) noexcept
	Copy an array and register young lanes with one old-range check.
template<class T, std::size_t N>
constexpr void	jam::unsafe_assign (std::array< weak_ptr< T >, N > &target, std::array< weak_ptr< T >, N > const &source) noexcept
	Bulk-copy weak pointer bits without registration; caller owns the barriers.
template<class T, std::size_t N>
constexpr void	jam::assign (std::array< weak_ptr< T >, N > &target, std::array< weak_ptr< T >, N > const &source) noexcept
	Copy weak fields and update remembered entries with one old-range check.
void	jam::collect () noexcept
	Collect the current heap; only registered roots remain meaningful outside it.
void	jam::collect_major () noexcept
	Collect both generations of the current heap; reset its collection countdown.
void	jam::collect_minor (bool promote=false) noexcept
	Collect the current heap's young generation; optionally promote survivors.
template<class T, std::size_t N, native::isa<> A>
void	jam::unsafe_assign (native::simd< ptr< T >, N, A > &target, native::simd< ptr< T >, N, A > const &source) noexcept
	Copy SIMD pointer bits without registering old-to-young slots.
template<class T, std::size_t N, native::isa<> A>
void	jam::assign (native::simd< ptr< T >, N, A > &target, native::simd< ptr< T >, N, A > const &source) noexcept
	Bulk-copy a register and register its old-to-young slots.
template<class T, std::size_t N, native::isa<> A, std::size_t K>
void	jam::unsafe_assign (native::wide< native::simd< ptr< T >, N, A >, K > &target, native::wide< native::simd< ptr< T >, N, A >, K > const &source) noexcept
	Copy a pointer register pack without registration; caller owns its barriers.
template<class T, std::size_t N, native::isa<> A, std::size_t K>
void	jam::assign (native::wide< native::simd< ptr< T >, N, A >, K > &target, native::wide< native::simd< ptr< T >, N, A >, K > const &source) noexcept
	Copy a pointer register pack with one bulk barrier per register.
template<class T, class U, class Owner, std::size_t N, native::isa<> A>
native::simd< U, N, A >	jam::gather (native::simd< ptr< T >, N, A > const &nodes, U Owner::*member, typename native::simd< ptr< T >, N, A >::mask_type active) noexcept
	Gather a member from selected lanes; inactive lanes return zero or null.
template<class T, class U, class Owner, std::size_t N, native::isa<> A>
native::simd< U, N, A >	jam::gather (native::simd< ptr< T >, N, A > const &nodes, U Owner::*member) noexcept
	Gather with the mask nodes != nullptr; inactive lanes return zero or null.
template<class T, class U, class Owner, std::size_t N, native::isa<> A, std::size_t K>
native::wide< native::simd< U, N, A >, K >	jam::gather (native::wide< native::simd< ptr< T >, N, A >, K > const &nodes, U Owner::*member, native::wide< typename native::simd< ptr< T >, N, A >::mask_type, K > const &active) noexcept
	Gather each register using the supplied masks, preserving lane and register order.
template<class T, class U, class Owner, std::size_t N, native::isa<> A, std::size_t K>
native::wide< native::simd< U, N, A >, K >	jam::gather (native::wide< native::simd< ptr< T >, N, A >, K > const &nodes, U Owner::*member) noexcept
	Compute all nonnull register masks, then gather the requested member.

Files
file	jam.ccm
	A compacting generational heap with four-byte pointers and tracing roots.
file	heap.ccm
	A double-mapped word arena with bounded parallel compaction.
file	simd.ccm
	SIMD compressed pointers and heap-relative gathers.
file	units.ccm
	Typed space units, conversions and size literals.