honeycomb_core::attributes

Trait UnknownAttributeStorage

Source
pub trait UnknownAttributeStorage:
    Any
    + Debug
    + Downcast {
    // Required methods
    fn new(length: usize) -> Self
       where Self: Sized;
    fn extend(&mut self, length: usize);
    fn n_attributes(&self) -> usize;
    fn merge(
        &self,
        trans: &mut Transaction,
        out: DartIdType,
        lhs_inp: DartIdType,
        rhs_inp: DartIdType,
    ) -> StmResult<()>;
    fn split(
        &self,
        trans: &mut Transaction,
        lhs_out: DartIdType,
        rhs_out: DartIdType,
        inp: DartIdType,
    ) -> StmResult<()>;
    fn try_merge(
        &self,
        trans: &mut Transaction,
        out: DartIdType,
        lhs_inp: DartIdType,
        rhs_inp: DartIdType,
    ) -> CMapResult<()>;
    fn try_split(
        &self,
        trans: &mut Transaction,
        lhs_out: DartIdType,
        rhs_out: DartIdType,
        inp: DartIdType,
    ) -> CMapResult<()>;

    // Provided methods
    fn force_merge(
        &self,
        out: DartIdType,
        lhs_inp: DartIdType,
        rhs_inp: DartIdType,
    ) { ... }
    fn force_split(
        &self,
        lhs_out: DartIdType,
        rhs_out: DartIdType,
        inp: DartIdType,
    ) { ... }
}
Expand description

Common trait implemented by generic attribute storages.

This trait contain attribute-agnostic function & methods.

§Note on force / regular / try semantics

We define three variants of split and merge methods (same as sews / unsews): force, regular, and try. Their goal is to provide different degrees of control vs convenience when using these operations. Documentation of each method shortly explains their individual quirks, below is a table summarizing the differences:

variantdescription
trydefensive impl, only succeding if the attribute operation is successful & the transaction isn’t invalidated
regularregular impl, which uses attribute fallback policies and will fail only if the transaction is invalidated
forceconvenience impl, which wraps the regular impl in a transaction that retries until success

Required Methods§

Source

fn new(length: usize) -> Self
where Self: Sized,

Constructor

§Arguments
  • length: usize – Initial length/capacity of the storage. It should correspond to the upper bound of IDs used to index the attribute’s values, i.e. the number of darts including the null dart.
§Return

Return a Self instance which yields correct accesses over the ID range 0..length.

Source

fn extend(&mut self, length: usize)

Extend the storage’s length

§Arguments
  • length: usize – length of which the storage should be extended.
Source

fn n_attributes(&self) -> usize

Return the number of stored attributes, i.e. the number of used slots in the storage, not its length.

Source

fn merge( &self, trans: &mut Transaction, out: DartIdType, lhs_inp: DartIdType, rhs_inp: DartIdType, ) -> StmResult<()>

Merge attributes at specified index

§Arguments
  • trans: &mut Transaction – Transaction used for synchronization.
  • out: DartIdentifier – Identifier to associate the result with.
  • lhs_inp: DartIdentifier – Identifier of one attribute value to merge.
  • rhs_inp: DartIdentifier – Identifier of the other attribute value to merge.
§Behavior (pseudo-code)
let new_val = match (attributes.remove(lhs_inp), attributes.remove(rhs_inp)) {
    (Some(v1), Some(v2)) => AttributeUpdate::merge(v1, v2),
    (Some(v), None) | (None, Some(v)) => AttributeUpdate::merge_undefined(Some(v)),
    None, None => AttributeUpdate::merge_undefined(None),
}
attributes.set(out, new_val);
§Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transacction passed as argument. The result should not be processed manually.

Source

fn split( &self, trans: &mut Transaction, lhs_out: DartIdType, rhs_out: DartIdType, inp: DartIdType, ) -> StmResult<()>

Split attribute to specified indices

§Arguments
  • trans: &mut Transaction – Transaction used for synchronization.
  • lhs_out: DartIdentifier – Identifier to associate the result with.
  • rhs_out: DartIdentifier – Identifier to associate the result with.
  • inp: DartIdentifier – Identifier of the attribute value to split.
§Behavior pseudo-code
(val_lhs, val_rhs) = AttributeUpdate::split(attributes.remove(inp).unwrap());
attributes[lhs_out] = val_lhs;
attributes[rhs_out] = val_rhs;
§Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

Source

fn try_merge( &self, trans: &mut Transaction, out: DartIdType, lhs_inp: DartIdType, rhs_inp: DartIdType, ) -> CMapResult<()>

Merge attributes at specified index

§Errors

This method will fail, returning an error, if:

  • the transaction cannot be completed
  • the merge fails (e.g. because one merging value is missing)

The returned error can be used in conjunction with transaction control to avoid any modifications in case of failure at attribute level. The user can then choose, through its transaction control policy, to retry or abort as he wishes.

Source

fn try_split( &self, trans: &mut Transaction, lhs_out: DartIdType, rhs_out: DartIdType, inp: DartIdType, ) -> CMapResult<()>

Split attribute to specified indices

§Errors

This method will fail, returning an error, if:

  • the transaction cannot be completed
  • the split fails (e.g. because there is no value to split from)

The returned error can be used in conjunction with transaction control to avoid any modifications in case of failure at attribute level. The user can then choose, through its transaction control policy, to retry or abort as he wishes.

Provided Methods§

Source

fn force_merge(&self, out: DartIdType, lhs_inp: DartIdType, rhs_inp: DartIdType)

Merge attributes at specified index

This variant is equivalent to merge, but internally uses a transaction that will be retried until validated.

Source

fn force_split(&self, lhs_out: DartIdType, rhs_out: DartIdType, inp: DartIdType)

Split attribute to specified indices

This variant is equivalent to split, but internally uses a transaction that will be retried until validated.

Implementations§

Source§

impl dyn UnknownAttributeStorage

Source

pub fn is<__T: UnknownAttributeStorage>(&self) -> bool

Returns true if the trait object wraps an object of type __T.

Source

pub fn downcast<__T: UnknownAttributeStorage>( self: Box<Self>, ) -> Result<Box<__T>, Box<Self>>

Returns a boxed object from a boxed trait object if the underlying object is of type __T. Returns the original boxed trait if it isn’t.

Source

pub fn downcast_rc<__T: UnknownAttributeStorage>( self: Rc<Self>, ) -> Result<Rc<__T>, Rc<Self>>

Returns an Rc-ed object from an Rc-ed trait object if the underlying object is of type __T. Returns the original Rc-ed trait if it isn’t.

Source

pub fn downcast_ref<__T: UnknownAttributeStorage>(&self) -> Option<&__T>

Returns a reference to the object within the trait object if it is of type __T, or None if it isn’t.

Source

pub fn downcast_mut<__T: UnknownAttributeStorage>(&mut self) -> Option<&mut __T>

Returns a mutable reference to the object within the trait object if it is of type __T, or None if it isn’t.

Implementors§