Represents a generation identifier associated with a stored object.

The generation identifier must change each time an object is updated.

A StorageGeneration should be treated as an opaque identifier, with its length and content specific to the particular storage system, except that there are three special values:

StorageGeneration::Unknown(), equal to the empty string, which can be used to indicate an unspecified generation.

StorageGeneration::NoValue(), equal to {1, 5}, which can be used to specify a condition that the object not exist.

StorageGeneration::Invalid(), equal to {1, 8}, which must not match any valid generation.

A storage implementation must ensure that the encoding of generations does not conflict with these two special generation values.

For example:

• t=0: Object does not exist, implicitly has generation G0, which may equal StorageGeneration::NoValue().

• t=1: Value V1 is written, storage system assigns generation G1.

• t=2: Value V2 is written, storage system assigns generation G2, which must not equal G1.

• t=3: Value V1 is written again, storage system assigns generation G3, which must not equal G1 or G2.

• t=4: Object is deleted, implicitly has generation G4, which may equal G0 and/or StorageGeneration::NoValue().

Note: Some storage implementations always use a generation of StorageGeneration::NoValue() for not-present objects. Other storage implementations may use other generations to indicate not-present objects. For example, if some sharding scheme is used pack multiple objects together into a “shard”, the generation associated with a not-present object may be the generation of the shard in which the object is missing.

Data members¶

std::string value;

The generation is indicated by a variable-length byte string (the “generation identifier”) followed by a sequence of bytes containing a bitwise-OR combination of the flags defined below:

constexpr const char kBaseGeneration = 1;

constexpr const char kDirty = 2;

constexpr const char kNewlyDirty = 16;

constexpr const char kNoValue = 4;

constexpr const char kInvalid = 8;

Flag values specified as a suffix of value.

Conversion operators¶

explicit operator bool() const;

Indicates whether a generation is specified.

Methods¶

static StorageGeneration Unknown();

Returns the special generation value that indicates the StorageGeneration is unspecified.

static StorageGeneration NoValue();

Returns the special generation value that corresponds to an object not being present.

static StorageGeneration Invalid();

Returns the invalid generation value guaranteed not to equal any valid generation.

static StorageGeneration FromUint64(uint64_t n);

Returns a base generation that encodes the specified 64-bit number.

static bool IsUint64(const StorageGeneration& generation);

Validates that generation may have been constructed from FromUint64.

void MarkDirty();

Modifies this generation to set kDirty and kNewlyDirty in the last (innermost) flag byte.

static StorageGeneration FromString(std::string_view s);

Returns a base generation that encodes the specified string.

static bool IsCleanValidValue(const StorageGeneration& generation);

Returns true if this is a clean base generation, not locally-modified, not StorageGeneration::NoValue() and not StorageGeneration::Invalid().

static std::string_view
DecodeString(const StorageGeneration& generation);

Inverse of FromString.

static StorageGeneration FromValues(const T&... value);

Returns a base generation that encodes one or more trivial values via memcpy.

static StorageGeneration Dirty(StorageGeneration generation);

Returns a generation that is marked as locally modified but conditioned on generation.

static StorageGeneration Clean(StorageGeneration generation);

Returns the “clean” base generation on which generation is based.

static bool Equivalent(std::string_view a, std::string_view b);

Determines if two generations are equivalent by comparing their canonical generations.

static bool IsDirty(const StorageGeneration& generation);

Checks if generation represents a locally-modified value.

static bool IsInnerLayerDirty(const StorageGeneration& generation);

Checks if the innermost layer of generation is locally-modified.

static StorageGeneration
Condition(const StorageGeneration& generation,
          StorageGeneration condition);

Returns a new_generation for which IsDirty(new_generation) == IsDirty(generation) and Clean(new_generation) == Clean(condition).

static StorageGeneration AddLayer(StorageGeneration generation);

Adds another layer of local modification to generation.

static bool IsConditional(const StorageGeneration& generation);

Checks if Clean(generation) != Unknown().

static bool IsConditionalOn(const StorageGeneration& generation,
                            const StorageGeneration& condition);

Checks if generation is the same as condition, ignoring dirty flags on the inner-most layer.

static bool EqualOrUnspecified(const StorageGeneration& generation,
                               const StorageGeneration& if_equal);

Checks if if_equal is unspecified, or equal to generation.

static bool
NotEqualOrUnspecified(const StorageGeneration& generation,
                      const StorageGeneration& if_not_equal);

Checks if if_not_equal is unspecified, or not equal to generation.

static bool IsUnknown(const StorageGeneration& generation);

Returns true if generation is equal to the special StorageGeneration::Unknown() value, i.e. an empty string.

static bool IsClean(const StorageGeneration& generation);

Returns true if generation represents a “clean” state without any local modifications.

static bool IsNoValue(const StorageGeneration& generation);

Returns true if generation is equal to the special NoValue() generation.

Friend functions¶

friend bool
operator==(const StorageGeneration& a, const StorageGeneration& b);

friend bool
operator==(std::string_view a, const StorageGeneration& b);

friend bool
operator==(const StorageGeneration& a, std::string_view b);

friend bool
operator!=(const StorageGeneration& a, const StorageGeneration& b);

friend bool
operator!=(const StorageGeneration& a, std::string_view b);

friend bool
operator!=(std::string_view a, const StorageGeneration& b);

Checks if two generations are Equivalent.

friend std::ostream&
operator<<(std::ostream& os, const StorageGeneration& g);

Prints a debugging string representation to an std::ostream.

friend H AbslHashValue(H h, const StorageGeneration& x);

Abseil hash support.