Sorts, filters and maps the view of one table. More...

#include <engine.hpp>

Inheritance diagram for morph::table::Engine:

Public Member Functions
	Engine (std::shared_ptr< DataSource > source, EngineOptions options={})
	Builds the engine; the initial view is every row in source order.
	Engine (Engine const &)=delete
Engine &	operator= (Engine const &)=delete
	Engine (Engine &&)=delete
Engine &	operator= (Engine &&)=delete
	~Engine () override
	Stops a running job and unsubscribes from the source.
std::expected< void, TableError >	setSort (SortChain chain)
	Sets the sort chain; an empty chain is source order.
std::expected< void, TableError >	setFilter (FilterSpec spec)
	Sets the filter.
SortChain const &	sort () const noexcept
	The current sort chain.
FilterSpec const &	filter () const noexcept
	The current filter.
std::span< ColumnInfo const >	columns () const noexcept
	The columns of the applied view: what cellAt indexes. A reset that changes the columns changes them when its view is applied, with a Reset change.
std::size_t	viewRowCount () const noexcept
	Rows in the view.
std::size_t	sourceRowCount () const
	Rows in the source the view was computed from.
std::optional< std::size_t >	sourceRowOf (std::size_t viewRow) const
	The source row shown at a view row.
std::optional< std::size_t >	viewRowOf (std::size_t sourceRow) const
	The view row showing a source row.
RowId	rowIdAt (std::size_t viewRow) const
	The key of the row at a view row.
std::optional< std::size_t >	viewRowOfKey (RowId const &key) const
	The view row of the row keyed `id`.
Cell	cellAt (std::size_t viewRow, std::size_t column) const
	One cell of the view.
std::span< std::uint32_t const >	view () const noexcept
	The view as source rows.
std::shared_ptr< RowSnapshot const > const &	viewSnapshot () const noexcept
	The snapshot the view's rows index.
bool	pending () const noexcept
	Whether a computation is in flight.
void	onViewChange (std::function< void(ViewChange const &)> handler)
	Sets the receiver of view changes, called on the owner after the view changed.
void	onPending (std::function< void(bool)> handler)
	Sets the receiver of pending() changes.
void	onError (std::function< void(TableError const &)> handler)
	Sets the receiver of errors no call could return: an injected service that threw in a job that did not run inside the call that asked for it. The sort and filter go back to those of the view shown.
EngineStats const &	stats () const noexcept
	Counters.
void	beginEdit (RowId const &key)
	Marks a row as being edited: with Deferred reorder it keeps its place through updates until endEdit.
void	endEdit (RowId const &key)
	Ends an edit; a held row moves to its sorted place now.
void	settleNow ()
	Releases every deferred row not being edited, as the settle interval does.
std::vector< RowId >	heldRows () const
	Rows currently held in place by Deferred reorder.

Detailed Description

Sorts, filters and maps the view of one table.

Owner-affine; see the file comment for how it executes. Holds a shared reference to its source and subscribes to its changes for its lifetime.

Definition at line 661 of file engine.hpp.

Constructor & Destructor Documentation

◆ Engine()

morph::table::Engine::Engine	(	std::shared_ptr< DataSource >	source,
		EngineOptions	options = {} )

inlineexplicit

Builds the engine; the initial view is every row in source order.

Parameters

source	The rows. Must not be null.
options	How the engine runs.

Definition at line 666 of file engine.hpp.

◆ ~Engine()

morph::table::Engine::~Engine ( )

inlineoverride

Stops a running job and unsubscribes from the source.

Definition at line 686 of file engine.hpp.

Member Function Documentation

◆ setSort()

std::expected< void, TableError > morph::table::Engine::setSort ( SortChain chain )

inline

Sets the sort chain; an empty chain is source order.

Keys are checked against the source's latest columns, which columns() shows once the view computed with them is applied.

Parameters

chain The keys, most significant first.

Returns: UnknownColumn when a key names no column; ServiceFailed when the sort ran inside the call and an injected service threw. The sort is then unchanged.

Definition at line 699 of file engine.hpp.

◆ setFilter()

std::expected< void, TableError > morph::table::Engine::setFilter ( FilterSpec spec )

inline

Sets the filter.

Parameters

spec	The filter; an empty spec shows every row.

Returns: The compile error, naming its column; or ServiceFailed when the filter ran inside the call and an injected service threw. The filter is then unchanged.

Definition at line 717 of file engine.hpp.

◆ sort()

SortChain const & morph::table::Engine::sort ( ) const

inlinenodiscardnoexcept

The current sort chain.

Returns: The chain.

Definition at line 729 of file engine.hpp.

◆ filter()

FilterSpec const & morph::table::Engine::filter ( ) const

inlinenodiscardnoexcept

The current filter.

Returns: The filter spec.

Definition at line 733 of file engine.hpp.

◆ columns()

std::span< ColumnInfo const > morph::table::Engine::columns ( ) const

inlinenodiscardnoexcept

The columns of the applied view: what cellAt indexes. A reset that changes the columns changes them when its view is applied, with a Reset change.

Returns: The columns.

Definition at line 739 of file engine.hpp.

◆ viewRowCount()

std::size_t morph::table::Engine::viewRowCount ( ) const

inlinenodiscardnoexcept

Rows in the view.

Returns: View row count.

Definition at line 743 of file engine.hpp.

◆ sourceRowCount()

std::size_t morph::table::Engine::sourceRowCount ( ) const

inlinenodiscard

Rows in the source the view was computed from.

Returns: Source row count.

Definition at line 747 of file engine.hpp.

◆ sourceRowOf()

std::optional< std::size_t > morph::table::Engine::sourceRowOf ( std::size_t viewRow ) const

inlinenodiscard

The source row shown at a view row.

Parameters

viewRow View row index.

Returns: The source row, or nothing past the end.

Definition at line 752 of file engine.hpp.

◆ viewRowOf()

std::optional< std::size_t > morph::table::Engine::viewRowOf ( std::size_t sourceRow ) const

inlinenodiscard

The view row showing a source row.

Parameters

sourceRow Source row index.

Returns: The view row, or nothing when the row is filtered out or past the end.

Definition at line 762 of file engine.hpp.

◆ rowIdAt()

RowId morph::table::Engine::rowIdAt ( std::size_t viewRow ) const

inlinenodiscard

The key of the row at a view row.

Parameters

viewRow View row index, below viewRowCount().

Returns: The row's key.

Definition at line 773 of file engine.hpp.

◆ viewRowOfKey()

std::optional< std::size_t > morph::table::Engine::viewRowOfKey ( RowId const & key ) const

inlinenodiscard

The view row of the row keyed id.

Parameters

key	A row key.

Returns: The view row, or nothing when no row in the view has that key.

Definition at line 778 of file engine.hpp.

◆ cellAt()

Cell morph::table::Engine::cellAt	(	std::size_t	viewRow,
		std::size_t	column ) const

inlinenodiscard

One cell of the view.

Parameters

viewRow	View row index, below viewRowCount().
column	Column index into columns().

Returns: The cell; empty for a column past columns().

Definition at line 789 of file engine.hpp.

◆ view()

std::span< std::uint32_t const > morph::table::Engine::view ( ) const

inlinenodiscardnoexcept

The view as source rows.

Returns: Source row indices in view order.

Definition at line 799 of file engine.hpp.

◆ viewSnapshot()

std::shared_ptr< RowSnapshot const > const & morph::table::Engine::viewSnapshot ( ) const

inlinenodiscardnoexcept

The snapshot the view's rows index.

Returns: The snapshot.

Definition at line 803 of file engine.hpp.

◆ pending()

bool morph::table::Engine::pending ( ) const

inlinenodiscardnoexcept

Whether a computation is in flight.

Returns: true from an asynchronous request until its result is applied.

Definition at line 807 of file engine.hpp.

◆ onViewChange()

void morph::table::Engine::onViewChange ( std::function< void(ViewChange const &)> handler )

inline

Sets the receiver of view changes, called on the owner after the view changed.

Parameters

handler The receiver; empty to stop receiving.

Definition at line 812 of file engine.hpp.

◆ onPending()

void morph::table::Engine::onPending ( std::function< void(bool)> handler )

inline

Sets the receiver of pending() changes.

Parameters

handler The receiver; empty to stop receiving.

Definition at line 816 of file engine.hpp.

◆ onError()

void morph::table::Engine::onError ( std::function< void(TableError const &)> handler )

inline

Sets the receiver of errors no call could return: an injected service that threw in a job that did not run inside the call that asked for it. The sort and filter go back to those of the view shown.

Parameters

handler The receiver; empty to stop receiving.

Definition at line 823 of file engine.hpp.

◆ stats()

EngineStats const & morph::table::Engine::stats ( ) const

inlinenodiscardnoexcept

Counters.

Returns: The engine's counters so far.

Definition at line 827 of file engine.hpp.

◆ beginEdit()

void morph::table::Engine::beginEdit ( RowId const & key )

inline

Marks a row as being edited: with Deferred reorder it keeps its place through updates until endEdit.

Parameters

key	The row's key.

Definition at line 832 of file engine.hpp.

◆ endEdit()

void morph::table::Engine::endEdit ( RowId const & key )

inline

Ends an edit; a held row moves to its sorted place now.

The commit that ends an edit usually patches the row just before, and that update reaches the engine on a later owner turn: the first job that includes it does not hold the row either, so it moves once rather than waiting for the settle interval.

Parameters

key	The row's key.

Definition at line 841 of file engine.hpp.

◆ settleNow()

void morph::table::Engine::settleNow ( )

inline

Releases every deferred row not being edited, as the settle interval does.

Definition at line 853 of file engine.hpp.

◆ heldRows()

std::vector< RowId > morph::table::Engine::heldRows ( ) const

inlinenodiscard

Rows currently held in place by Deferred reorder.

Returns: Their keys.

Definition at line 860 of file engine.hpp.

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

morph/table/engine.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Engine()

◆ ~Engine()

Member Function Documentation

◆ setSort()

◆ setFilter()

◆ sort()

◆ filter()

◆ columns()

◆ viewRowCount()

◆ sourceRowCount()

◆ sourceRowOf()

◆ viewRowOf()

◆ rowIdAt()

◆ viewRowOfKey()

◆ cellAt()

◆ view()

◆ viewSnapshot()

◆ pending()

◆ onViewChange()

◆ onPending()

◆ onError()

◆ stats()

◆ beginEdit()

◆ endEdit()

◆ settleNow()

◆ heldRows()