Struct QWSDataView

pub struct QWSDataView<'a> { /* private fields */ }

A view into the QuantumWorldState that may represent a partially collapsed or fully collapsed view, and / or the results of a query.

A QWSDataView is a perspective from which all elements in the world have a QWSElementStatus, for example: KnownPresent, KnownAbsent or Superposition An element that is KnownPresent in one QWSDataView might be KnownAbsent in another.

A view may be collapsed in order to constrain the view’s perspective such that elements are definitely known to exist or not exist, rather than being in an indefinite state. A QWSDataView may also represent the results of an executed query, and only the subset of elements found by the query will be available from the view.

Query and collapse can be used together in the same view, to refine the set of elements that meet the query criteria and are simultaneously capable of coexisting with each other at the same epoch.

QWSDataViews are intended to be inexpensive to clone, and common use cases involve using multiple views of the same world.

QWSDataView borrows the QuantumWorldState, so all views must be dropped before new transactions can be added.

---

Note

The choice to use the same object for both collapsing and querying was made because it is a valid use case to perform some collapsing, then perform some querying, then perform some additional collapsing in response to the results found by the query. Therefore, the QWSDataView is the single object responsible for holding both query results and partially collapsed state.

Implementations

impl<'a> QWSDataView<'a>

pub fn collapse_transactions( self, collapse_transactions: &[QWSTransactionID], ) -> Result<Self, QWSError>

Returns a partially collapsed view in which each of the supplied transactions has occurred. After the collapse, all elements that are entangled with any of the supplied transactions have a status of KnownPresent or KnownAbsent, when accessed from the resultant view. Elements that remain unentangled with any transactions in the view will keep the Superposition status.

If two or more of the supplied transactions reference elements that cannot coexist at the same epoch, then this function will return an error.

Regardless of whether or not this function was sucessful, the calling QWSDataView will be consumed.

pub fn collapse_view( self, other_view: QWSDataView<'_>, ) -> Result<Self, QWSError>

Returns a partially collapsed view which represents the combined state of collapse from both self and other_view. After the collapse, all elements that had a status of KnownPresent or KnownAbsent in either view will have that respective status in the new resultant view. Elements that were in Superposition in both views will retain that status.

If any elements is KnownPresent in one view and KnownAbsent in the other, that means the views are in conflict and this function will return an error.

Regardless of whether or not this function was sucessful, the calling QWSDataView and the other_view will both be consumed.

pub fn fully_collapse(self) -> Result<Self, QWSError>

Returns a fully collapsed view in which no elements exist in Superposition.

If two or more of the elements in the view cannot coexist at the same epoch, then this function will return an error. If get_conflicting_transactions() returns a zero-length slice, then this function will be sucessful, otherwise it will fail.

Regardless of whether or not this function was sucessful, the calling QWSDataView will be consumed.

pub fn conflicts_with(&self, other_view: &QWSDataView<'_>) -> bool

Returns false if the specified other_view can be collapsed into the view without any conflicts. Returns true if an attempt to collapse will fail.

pub fn get_element_status(&self, element_id: QWSElementID) -> QWSElementStatus

Returns the status for the indicated element from the perspective of the view.

OPEN QUESTION

Should this return QWSElementStatus::Unknown if the element being asked about is not part of the query? Currently this function takes the collapse state of the view into account, but not the query.

pub fn get_collapsed_transactions(&self) -> &[QWSTransactionID]

Returns a reference to a slice of QWSTransactionIDs of all collapsed transactions within the view

pub fn get_conflicting_transactions(&mut self) -> &[QWSTransactionID]

Returns a reference to a slice of QWSTransactionIDs of all transactions visible within the view that conflict with at least one other transaction also visible within the view.

If there are no conflicting transactions, then fully_collapse() will succeed, so this function can be thought of as a way iterate through all of the different possible world states that can exist.

Iterating Possible World States

The below code will visit every possible unique fully collapsed world state that is accessible from the QWSDataView. At the limit, this may be an O(n!) operation, so only do this when you are reasonably comfortable you are working with a manageable set.

fn recursive_collapse(current_view : &mut QWSDataView) {
    let conflicting_transactions = current_view.get_conflicting_transactions().to_vec();
    if conflicting_transactions.len() > 0 {
        for transaction_id in conflicting_transactions {
            let mut partially_collapsed_view = current_view.clone().collapse_transactions(&[transaction_id]).unwrap();
            recursive_collapse(&mut partially_collapsed_view);
        }
    } else {
        let mut _fully_collapsed_view = current_view.clone().fully_collapse();
    }
}

recursive_collapse(&mut qws.new_view());

Note

Conceptually, this isn’t a mutating API, but we need &mut self for internal implementation reasons. As you can see above, this leads to a suboptimal copy of the slice returned by get_conflicting_transactions() that would otherwise be unnecessary.

pub fn visit_fully_collapsed_views<VisitorClosure: Fn(QWSDataView<'_>)>( &mut self, visitor_closure: VisitorClosure, )

Executes the provided closure for every possible fully collapsed view visible from self

Example

// Print the number of transactions in each fully-collapsed end-state view
qws.new_view().visit_fully_collapsed_views(|collapsed_view : QWSDataView| {
    println!("transaction count = {}", collapsed_view.get_collapsed_transactions().len());
});

PERFORMANCE WARNING

This function can potentially require O(n!) time to execute, so you should only call it from views that have manageable characteristics.
This function’s implementation corresponds to the sample code in get_conflicting_transactions().

pub fn query_contains_key(self, key: &QWSMetaData) -> Result<Self, QWSError>

Returns a view that has been narrowed such that only elements with a key matching the supplied parameter will be visible from the view
Regardless of whether or not this function was sucessful, the calling QWSDataView will be consumed.

pub fn query_key_equals_value( self, key: &QWSMetaData, value: &QWSMetaData, ) -> Result<Self, QWSError>

Returns a view that has been narrowed such that only elements with a key and value pair matching the supplied parameters will be visible from the view
Regardless of whether or not this function was sucessful, the calling QWSDataView will be consumed.

pub fn query_explicit_set( self, query_set: &[QWSElementID], ) -> Result<Self, QWSError>

Returns a view that has been narrowed such that only elements with QWSElementIDs from the provided slice will be visible from the view.
This can be thought of as a “back door” to allow external logic to narrow down the query result set based on criteria aside from the meta-data.
Regardless of whether or not this function was sucessful, the calling QWSDataView will be consumed.

NOTE

Elements outside the query set don’t affect the fully collapsed states that will be visited when iterating the states accessible from a view. Therefore it is advantageous to narrow the view’s query set as much as possible prior to attempting to iterate over fully collapsed states.

pub fn elements_iter(&self) -> QWSElementsIterator<'_, '_>

Returns new QWSElementsIterator to iterate over the elements visible from the view.

If the view has been narrowed by a query, only elements that match the query criteria will be visited, otherwise only the element status will affect the iterator’s behavior. The iterator will visit elements in both the KnownPresent and Superposition status. KnownAbsent elements will not be visited.

Trait Implementations

impl<'a> Clone for QWSDataView<'a>

fn clone(&self) -> QWSDataView<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for QWSDataView<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.