EphemeralRelation.h File Reference

Writer path and lifetime helpers for ephemeral relations. More...

#include "LifecycleManager.h"
#include "ObjectManager.h"
#include <string>
#include <utility>
#include <vector>

Go to the source code of this file.

Namespaces
namespace	nt
	Contains the Relational NT runtime managers and API facade.

Enumerations
enum class	nt::Ephemeral::Tier { Scratch , Named }
	Lifetime class of a freshly produced ephemeral relation. More...

Functions
std::vector< std::string >	nt::Ephemeral::SplitPath (const std::string &path)
	Splits a slash-joined logical path into registry components.
std::string	nt::Ephemeral::ComposeRoot (const std::string &generator_identity, const std::vector< std::pair< std::string, std::string > > &schema, const std::vector< std::string > &base_roots)
	Deterministic merkle_root for an ephemeral relation.
ObjectManager::registry *	nt::Ephemeral::Register (ObjectManager &objects, LifecycleManager &lifecycles, const std::string &session_hash, Tier tier, const std::string &name, ObjectManager::ephemeral_object_type::Generator generator, ObjectManager::ephemeral_object_type::Cardinality cardinality, const std::string &generator_identity, const std::vector< std::pair< std::string, std::string > > &schema, const std::vector< std::string > &dependencies)
	Registers an ephemeral relation produced by a relational operation.
std::size_t	nt::Ephemeral::ReleaseSession (ObjectManager &objects, LifecycleManager &lifecycles, const std::string &session_hash)
	Releases all ephemeral relations owned by a session.

Detailed Description

Writer path and lifetime helpers for ephemeral relations.

An ephemeral relation has no tuple storage of its own; its tuples are produced on demand by a generator (see ObjectManager.h). Relational-algebra operations (select, project, join) all yield one. The functions here register such a relation into the object manager, hash its identity, pin the base relations it is defined atop, and release session-owned entries at session close.

They are free functions over an ObjectManager and a LifecycleManager, not a stateful manager object.

See docs/ephemeral-relations.org for the lifetime model.

Enumeration Type Documentation

Tier

enum class nt::Ephemeral::Tier

strong

Lifetime class of a freshly produced ephemeral relation.

Naming is what makes a result outlive its cursor: an anonymous result is owned by nobody.

• Scratch: an anonymous per-statement intermediate. Registered under /system/sessions/<session>/scratch/<root> and not session-pinned, so it is collected by reference counting once its consuming cursor closes.
• Named: a view-like binding. Registered under /system/sessions/<session>/ephemeral/<name> with one session-ownership Pin, so it survives between commands and can be re-requested. Released at rnt_session_close or (later) by the idle reaper.

Function Documentation

ComposeRoot()

std::string nt::Ephemeral::ComposeRoot	(	const std::string &	generator_identity,
		const std::vector< std::pair< std::string, std::string > > &	schema,
		const std::vector< std::string > &	base_roots )

Deterministic merkle_root for an ephemeral relation.

Hashes SHA256 over the generator identity, the schema, and the merkle_roots of the declared base relations. Two ephemerals with the same operator, schema, and base roots hash identically, so a repeated query reuses one registry entry instead of creating duplicates; rebinding a base produces a new root that propagates like a tuple insertion in a stored relation.

Schema entries and base roots are sorted internally, so input order does not affect the result.

Parameters

generator_identity	Stable label of the producing operator/builtin (e.g. "join", "select:age", "eq").
schema	(attribute_name, attribute_type) pairs.
base_roots	merkle_roots of the base relations, any order.

Returns

64-char lowercase-hex SHA256 digest.

Register()

ObjectManager::registry * nt::Ephemeral::Register	(	ObjectManager &	objects,
		LifecycleManager &	lifecycles,
		const std::string &	session_hash,
		Tier	tier,
		const std::string &	name,
		ObjectManager::ephemeral_object_type::Generator	generator,
		ObjectManager::ephemeral_object_type::Cardinality	cardinality,
		const std::string &	generator_identity,
		const std::vector< std::pair< std::string, std::string > > &	schema,
		const std::vector< std::string > &	dependencies )

Registers an ephemeral relation produced by a relational operation.

Resolves each dependency in the registry to read its current merkle_root (for the identity hash) and to take a structural Pin on it: a base relation cannot be GC'd while an ephemeral is defined atop it. Then registers an EphemeralRelation IObject with an ephemeral_object_type carrying the generator and cardinality. For Tier::Named, an extra session-ownership Pin is taken so the entry outlives its cursor.

Idempotent: an existing entry at the target path (identical scratch root, or a live named binding) is returned without re-registering or double-pinning.

The caller should Monitor the returned entry when it opens a cursor over it; a Scratch entry with no cursor and no session pin lingers until session close.

Parameters

objects	Registry to register into.
lifecycles	Lifecycle manager for the dependency / ownership pins.
session_hash	Owning session's hash (the namespace parent).
tier	Scratch (anonymous) or Named (session-owned).
name	Leaf name for Tier::Named; ignored for Tier::Scratch (the composed root is used as the leaf instead).
generator	Tuple-producing generator for this relation.
cardinality	Finite / ConstrainedFinite / AlephZero / Continuum.
generator_identity	Stable operator label, see ComposeRoot.
schema	(attribute_name, attribute_type) pairs.
dependencies	Slash-joined logical paths (no leading slash) of the base relations this is defined atop, e.g. "system/snapshots/<h>/relations/<rel>". Stored verbatim on the object and re-split at GC time. Every path must resolve; an unresolvable dependency fails the whole registration, since a stored-but-unpinned path would make CascadeEphemeral Unpin a hold it never took.

Returns

Borrowed pointer to the registered (or pre-existing) entry, or nullptr on error (empty session hash, empty name for Tier::Named, or any unresolvable dependency).

ReleaseSession()

std::size_t nt::Ephemeral::ReleaseSession	(	ObjectManager &	objects,
		LifecycleManager &	lifecycles,
		const std::string &	session_hash )

Releases all ephemeral relations owned by a session.

Called by rnt_session_close before the session entry is removed. Named entries directly under the session's "ephemeral" subdir have their session-ownership Pin released (collecting them when no cursor or dependent still holds them, cascading their base-relation Unpins). Scratch entries under the session's "scratch" subdir were never session-pinned; any that linger with no open cursor are collected directly. Entries still held by an open cursor are left for the normal handle-release path.

Parameters

objects	Registry to walk.
lifecycles	Lifecycle manager driving the releases.
session_hash	Session whose ephemerals to release.

Returns

Number of entries released or collected.

SplitPath()

std::vector< std::string > nt::Ephemeral::SplitPath

(

const std::string &

path

)

Splits a slash-joined logical path into registry components.

Drops a leading slash and any empty segments, matching split_path in the C API layer. Used by the writer path here and by LifecycleManager::CascadeEphemeral when re-splitting stored dependency paths at GC time.