Thread-safe owner of a revisioned Timeline document. More...

#include <document_session.hpp>

Public Member Functions
	~DocumentSession ()
	Releases the session and its retained sink.
	DocumentSession (const DocumentSession &)=delete
DocumentSession &	operator= (const DocumentSession &)=delete
runtime::Result< WriterToken, TransactionError >	register_writer ()
	Registers a distinct writer until max_writers or ID space is exhausted.
runtime::Result< WriterToken, TransactionError >	register_writer (WriterCapabilityMask mask)
	Registers a distinct writer whose authority is fixed at mask.
std::optional< WriterCapabilityMask >	writer_capabilities (WriterToken::Provenance provenance) const noexcept
	Returns the authority fixed at registration for provenance.
DocumentView	current () const noexcept
	Returns one atomic snapshot/revision observation without taking the writer lock.
std::shared_ptr< const Project >	snapshot () const noexcept
	Returns the currently published immutable snapshot.
DocumentRevision	revision () const noexcept
	Returns the revision paired with the currently published snapshot.
bool	is_current_publication (const CommitResult &result) const noexcept
	Reports whether result is the session's exact current publication.
bool	is_gesture_open (WriterToken::Provenance provenance, UndoGroupId group) const noexcept
	Reports whether provenance/group owns the session's current open gesture.
runtime::Result< CommitResult, TransactionError >	submit (WriterToken &writer, Transaction transaction)
	Applies and, when configured, durably journals one transaction.
runtime::Result< CommitResult, TransactionError >	undo (WriterToken &writer)
	Applies the newest closed undo group as a durable history transaction.
runtime::Result< CommitResult, TransactionError >	redo (WriterToken &writer)
	Reapplies the newest redo group as a durable history transaction.
bool	can_undo () const noexcept
	Reports whether a closed undo group is currently available.
bool	can_redo () const noexcept
	Reports whether a redo group is currently available.
CommandJournal	journal () const
	Returns a locked copy of the bounded in-memory command journal.
bool	checkpoint (DocumentRevision durable_revision)
	Advances the journal checkpoint through an existing revision.

Static Public Member Functions
static runtime::Result< std::unique_ptr< DocumentSession >, TransactionError >	create (Project initial, SessionLimits limits={})
	Creates a session at revision zero without an external durable sink.
static runtime::Result< std::unique_ptr< DocumentSession >, TransactionError >	create (Project initial, SessionLimits limits, std::shared_ptr< JournalSink > journal_sink)
	Creates a session at revision zero and initializes a durable sink.
static runtime::Result< std::unique_ptr< DocumentSession >, TransactionError >	restore (Project checkpoint, DocumentRevision checkpoint_revision, SessionLimits limits, std::shared_ptr< JournalSink > journal_sink)
	Restores a session from a checkpoint already present in a durable sink.

Friends
class	detail::DocumentSessionPreviewAccess

Detailed Description

Thread-safe owner of a revisioned Timeline document.

Reads publish immutable snapshots atomically. Submissions, undo/redo, checkpointing, and writer registration are serialized internally and must not run on a real-time audio thread. When a JournalSink is attached, a revision is published only after the sink acknowledges the whole journal entry as durable. A failed durability acknowledgement permanently rejects subsequent durable writes from this session.

Constructor & Destructor Documentation

◆ ~DocumentSession()

pulp::timeline::DocumentSession::~DocumentSession ( )

Releases the session and its retained sink.

The caller must ensure no member call is in progress during destruction.

◆ DocumentSession()

pulp::timeline::DocumentSession::DocumentSession ( const DocumentSession & )

delete

Member Function Documentation

◆ can_redo()

bool pulp::timeline::DocumentSession::can_redo ( ) const

noexcept

Reports whether a redo group is currently available.

◆ can_undo()

bool pulp::timeline::DocumentSession::can_undo ( ) const

noexcept

Reports whether a closed undo group is currently available.

◆ checkpoint()

bool pulp::timeline::DocumentSession::checkpoint ( DocumentRevision durable_revision )

Advances the journal checkpoint through an existing revision.

With a sink, the reconstructed checkpoint is installed durably before in-memory entries are discarded. Failure leaves the prior in-memory checkpoint intact; a sink failure also disables later durable writes.

◆ create() [1/2]

runtime::Result< std::unique_ptr< DocumentSession >, TransactionError > pulp::timeline::DocumentSession::create	(	Project	initial,
		SessionLimits	limits,
		std::shared_ptr< JournalSink >	journal_sink )

static

Creates a session at revision zero and initializes a durable sink.

The sink is checkpointed and then validated before attachment. The session retains shared ownership of it and invokes it while holding the session writer lock.

Returns: The session, or JournalDurability when initialization or validation is not acknowledged.

◆ create() [2/2]

runtime::Result< std::unique_ptr< DocumentSession >, TransactionError > pulp::timeline::DocumentSession::create	(	Project	initial,
		SessionLimits	limits = {} )

static

Creates a session at revision zero without an external durable sink.

Parameters

initial	Initial immutable document value.
limits	Fixed resource ceilings for the session.

Returns: The session, or WriterLimit/SequenceExhausted when it cannot allocate the required session state.

◆ current()

DocumentView pulp::timeline::DocumentSession::current ( ) const

noexcept

Returns one atomic snapshot/revision observation without taking the writer lock.

◆ is_current_publication()

bool pulp::timeline::DocumentSession::is_current_publication ( const CommitResult & result ) const

noexcept

Reports whether result is the session's exact current publication.

Snapshot identity and revision are compared from one atomic observation.

◆ is_gesture_open()

bool pulp::timeline::DocumentSession::is_gesture_open	(	WriterToken::Provenance	provenance,
		UndoGroupId	group ) const

noexcept

Reports whether provenance/group owns the session's current open gesture.

This control-thread query reads the authoritative session lifecycle under the writer lock. It retains neither the provenance nor submission authority.

◆ journal()

CommandJournal pulp::timeline::DocumentSession::journal ( ) const

Returns a locked copy of the bounded in-memory command journal.

◆ operator=()

DocumentSession & pulp::timeline::DocumentSession::operator= ( const DocumentSession & )

delete

◆ redo()

runtime::Result< CommitResult, TransactionError > pulp::timeline::DocumentSession::redo ( WriterToken & writer )

Reapplies the newest redo group as a durable history transaction.

The supplied token determines the IDs of the generated history transaction. Redo is rejected while a gesture is open.

◆ register_writer() [1/2]

runtime::Result< WriterToken, TransactionError > pulp::timeline::DocumentSession::register_writer ( )

Registers a distinct writer until max_writers or ID space is exhausted.

The writer carries full authority and no quota.

◆ register_writer() [2/2]

runtime::Result< WriterToken, TransactionError > pulp::timeline::DocumentSession::register_writer ( WriterCapabilityMask mask )

Registers a distinct writer whose authority is fixed at mask.

The mask is copied into session state and is never reachable from the returned token, so it cannot be widened, narrowed, or replaced for the life of the writer. Submissions are admitted against it inside the session's own admission path, so there is no wrapper to bypass.

Undo and redo are admitted against the same classes, because the inverse of a creation is a removal: without that check a writer denied a class could still reach its effect by undoing another writer's work. Quotas are not charged there, since replaying history adds no new content.

◆ restore()

runtime::Result< std::unique_ptr< DocumentSession >, TransactionError > pulp::timeline::DocumentSession::restore	(	Project	checkpoint,
		DocumentRevision	checkpoint_revision,
		SessionLimits	limits,
		std::shared_ptr< JournalSink >	journal_sink )

static

Restores a session from a checkpoint already present in a durable sink.

This operation validates exact snapshot and revision agreement without rewriting the sink. The session retains shared ownership of the sink.

Returns: The restored session, or JournalDurability when the sink does not validate the supplied checkpoint.

◆ revision()

DocumentRevision pulp::timeline::DocumentSession::revision ( ) const

noexcept

Returns the revision paired with the currently published snapshot.

◆ snapshot()

std::shared_ptr< const Project > pulp::timeline::DocumentSession::snapshot ( ) const

noexcept

Returns the currently published immutable snapshot.

◆ submit()

runtime::Result< CommitResult, TransactionError > pulp::timeline::DocumentSession::submit	(	WriterToken &	writer,
		Transaction	transaction )

Applies and, when configured, durably journals one transaction.

The token must belong to this session and match the transaction writer. The transaction must target the current revision and use strictly increasing writer-scoped IDs. Equivalent retries within the result cache return their original CommitResult without applying twice. Successful document commits advance the revision by one and invalidate the redo stack. A commandless End/Cancel closes the matching open gesture without changing the document revision or journal; other empty transactions are rejected.

Returns: The published commit, or a TransactionError describing identity, revision, gesture, quota, model, or durability rejection.

◆ undo()

runtime::Result< CommitResult, TransactionError > pulp::timeline::DocumentSession::undo ( WriterToken & writer )

Applies the newest closed undo group as a durable history transaction.

The supplied token determines the IDs of the generated history transaction. Undo is rejected while a gesture is open.

◆ writer_capabilities()

std::optional< WriterCapabilityMask > pulp::timeline::DocumentSession::writer_capabilities ( WriterToken::Provenance provenance ) const

noexcept

Returns the authority fixed at registration for provenance.

Returns nullopt when the provenance does not name a writer of this session. This is an observation for tests and diagnostics; it hands back a copy and never a handle that could mutate the stored mask.

◆ detail::DocumentSessionPreviewAccess

friend class detail::DocumentSessionPreviewAccess

friend

The documentation for this class was generated from the following file:

/home/runner/work/pulp/pulp/core/timeline/include/pulp/timeline/document_session.hpp

Pulp 1.88.0 Cross-platform audio plugin framework

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~DocumentSession()

◆ DocumentSession()

Member Function Documentation

◆ can_redo()

◆ can_undo()

◆ checkpoint()

◆ create() [1/2]

◆ create() [2/2]

◆ current()

◆ is_current_publication()

◆ is_gesture_open()

◆ journal()

◆ operator=()

◆ redo()

◆ register_writer() [1/2]

◆ register_writer() [2/2]

◆ restore()

◆ revision()

◆ snapshot()

◆ submit()

◆ undo()

◆ writer_capabilities()

Friends And Related Symbol Documentation

◆ detail::DocumentSessionPreviewAccess