Struct fdb::tuple::Versionstamp

pub struct Versionstamp { /* private fields */ }

Used to represent values written by versionstamp operations with a Tuple.

Versionstamp contains twelve bytes. The first ten bytes are the “transaction” version, and they are usually assigned by the database in such a way that all transactions receive a different version that is consistent with a serialization order of the transactions within the database (One can use the get_versionstamp method to retrieve this version from a Transaction). This also implies that the transaction version of newly committed transactions will be monotonically increasing over time. The final two bytes are the “user” version and should be set by the client. This allows the user to use this type to impose a total order of items across multiple transactions in the database in a consistent and conflict-free way.

All Versionstamps can exist in one of two states: “incomplete” and “complete”. An “incomplete” Versionstamp is a Versionstamp that has not been initialized with a meaningful transaction version. For example, this might be used with a Versionstamp that one wants to fill in with the current transaction’s version information. A “complete” Versionstamp, in contradistinction, is one that has been assigned a meaningful transaction version. This is usually the case if one is reading back a Versionstamp from the database.

Example usage might be to do something like the following:

let tr_version = fdb_database
    .run(|tr| async move {
        let t = {
            let mut tup = Tuple::new();
            tup.push_back::<String>(String::from("prefix"));
            tup.push_back::<Versionstamp>(Versionstamp::incomplete(0));
            tup
        };

        unsafe {
            tr.mutate(
                MutationType::SetVersionstampedKey,
                t.pack_with_versionstamp(Bytes::new())?,
                Bytes::new(),
            );
        }

        Ok(unsafe { tr.get_versionstamp() })
    })
    .await?
    .get()
    .await?;

let vs = fdb_database
    .run(|tr| async move {
        let subspace = Subspace::new(Bytes::new()).subspace(&{
            let mut tup = Tuple::new();
            tup.push_back::<String>("prefix".to_string());
            tup
        });

        let subspace_range = subspace.range(&Tuple::new());

        let key = subspace_range
            .into_stream(&tr, RangeOptions::default())
            .take(1)
            .next()
            .await
            .unwrap()?
            .into_key();

        Ok(subspace
            .unpack(&key.into())?
            .get::<&Versionstamp>(0)
            .ok_or(FdbError::new(TUPLE_GET))?
            .clone())
    })
    .await?;

assert_eq!(vs, Versionstamp::complete(tr_version, 0));

Here, an incomplete Versionstamp is packed and written to the database with SetVersionstampedKey mutation type.

After committing, we then attempt to read back the same key that we just wrote. Then we verify the invariant that the deserialized Versionstamp is the same as a complete Versionstamp value created from the first transaction’s version information.

Implementations

impl Versionstamp

pub fn complete(tr_version: Bytes, user_version: u16) -> Versionstamp

Creates a complete Versionstamp instance with the given transaction and user versions.

Panic

Panics if the length of the transaction version is incorrect.

pub fn from_bytes(version_bytes: Bytes) -> Versionstamp

Creates a value of Versionstamp type based on the given byte array.

Panic

Panics if the length of the byte array is incorrect.

pub fn incomplete(user_version: u16) -> Versionstamp

Creates an incomplete Versionstamp instance with the given user version.

pub fn get_bytes(&self) -> Bytes

Retrieve a byte representation of this Versionstamp.

pub fn get_transaction_version(&self) -> Bytes

Retrieve the portion of this Versionstamp that is set by the database.

pub fn get_user_version(&self) -> u16

Retrieve the portion of this Versionstamp that is set by the user.

pub fn is_complete(&self) -> bool

Whether this Versionstamp’s transaction version is meaningful.

pub fn into_parts(self) -> (Bytes, u16, bool)

Extract transaction version, user version and completion flag from Versionstamp.

Trait Implementations

impl Clone for Versionstamp

fn clone(&self) -> Versionstamp

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Versionstamp

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

Formats the value using the given formatter.

impl Ord for Versionstamp

fn cmp(&self, other: &Versionstamp) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Versionstamp> for Versionstamp

fn eq(&self, other: &Versionstamp) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<Versionstamp> for Versionstamp

fn partial_cmp(&self, other: &Versionstamp) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<(Bytes, u16)> for Versionstamp

fn try_from(value: (Bytes, u16)) -> FdbResult<Versionstamp>

Bytes value would be the “transaction” version and u16 value would be the “user” version.

type Error = FdbError

The type returned in the event of a conversion error.

impl Eq for Versionstamp

impl StructuralEq for Versionstamp

impl StructuralPartialEq for Versionstamp

impl<'a> TupleElementGet<'a> for &'a Versionstamp

impl TupleElementPop for Versionstamp

impl TupleElementPush for Versionstamp