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:
variant | description |
---|---|
try | defensive impl, only succeding if the attribute operation is successful & the transaction isn’t invalidated |
regular | regular impl, which uses attribute fallback policies and will fail only if the transaction is invalidated |
force | convenience impl, which wraps the regular impl in a transaction that retries until success |
Required Methods§
Sourcefn new(length: usize) -> Selfwhere
Self: Sized,
fn new(length: usize) -> Selfwhere
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
.
Sourcefn extend(&mut self, length: usize)
fn extend(&mut self, length: usize)
Extend the storage’s length
§Arguments
length: usize
– length of which the storage should be extended.
Sourcefn n_attributes(&self) -> usize
fn n_attributes(&self) -> usize
Return the number of stored attributes, i.e. the number of used slots in the storage, not its length.
Sourcefn merge(
&self,
trans: &mut Transaction,
out: DartIdType,
lhs_inp: DartIdType,
rhs_inp: DartIdType,
) -> StmResult<()>
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.
Sourcefn split(
&self,
trans: &mut Transaction,
lhs_out: DartIdType,
rhs_out: DartIdType,
inp: DartIdType,
) -> StmResult<()>
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.
Sourcefn try_merge(
&self,
trans: &mut Transaction,
out: DartIdType,
lhs_inp: DartIdType,
rhs_inp: DartIdType,
) -> CMapResult<()>
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.
Sourcefn try_split(
&self,
trans: &mut Transaction,
lhs_out: DartIdType,
rhs_out: DartIdType,
inp: DartIdType,
) -> CMapResult<()>
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§
Sourcefn force_merge(&self, out: DartIdType, lhs_inp: DartIdType, rhs_inp: DartIdType)
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.
Sourcefn force_split(&self, lhs_out: DartIdType, rhs_out: DartIdType, inp: DartIdType)
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
impl dyn UnknownAttributeStorage
Sourcepub fn is<__T: UnknownAttributeStorage>(&self) -> bool
pub fn is<__T: UnknownAttributeStorage>(&self) -> bool
Returns true if the trait object wraps an object of type __T
.
Sourcepub fn downcast<__T: UnknownAttributeStorage>(
self: Box<Self>,
) -> Result<Box<__T>, Box<Self>>
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.
Sourcepub fn downcast_rc<__T: UnknownAttributeStorage>(
self: Rc<Self>,
) -> Result<Rc<__T>, Rc<Self>>
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.
Sourcepub fn downcast_ref<__T: UnknownAttributeStorage>(&self) -> Option<&__T>
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.
Sourcepub fn downcast_mut<__T: UnknownAttributeStorage>(&mut self) -> Option<&mut __T>
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.