ludus::foundation::identity

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/foundation/identity/include/ludus/foundation/identity/handle.hpp

Related declarations

• ludus::foundation::identity::AssetTag
• ludus::foundation::identity::EntropySource
• ludus::foundation::identity::Handle
• ludus::foundation::identity::InstanceTag
• ludus::foundation::identity::PersistentObjectKey
• ludus::foundation::identity::SourceObjectTag
• ludus::foundation::identity::TypedUuid
• ludus::foundation::identity::Uuid

Enumerations

GenerationStatus

enum class GenerationStatus : uint8

Result of advancing a released slot's generation.

Related types: uint8

Advanced

Advanced

The generation was incremented; the slot may be reused with the new value.

Retired

Retired

The slot was released at TERMINAL_GENERATION. It must be retired permanently for its owner; the generation is unchanged and never wraps.

InvalidGeneration

InvalidGeneration

The input was zero, which no registry issues; the generation is unchanged.

Declared in modules/foundation/identity/include/ludus/foundation/identity/handle.hpp

LifetimeIdStatus

enum class LifetimeIdStatus : uint8

Result of issuing a registry lifetime token.

Related types: uint8

Success

Success

A fresh token was written to the output.

IdentityExhausted

IdentityExhausted

The source reached its terminal value; it never wraps. The output is unchanged.

Declared in modules/foundation/identity/include/ludus/foundation/identity/lifetime.hpp

UuidPolicy

enum class UuidPolicy : uint8

Which UUID values an operation accepts.

Related types: uint8

RequireVersion4

RequireVersion4

Accept only a nonnil RFC 9562 version-4 UUID: an actual durable identity.

AllowNilOrVersion4

AllowNilOrVersion4

Also accept the nil UUID, the explicit sentinel of an absent optional reference.

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UuidStatus

enum class UuidStatus : uint8

Result of a UUID validation, codec or construction operation.

Related types: uint8

Success

Success

The operation succeeded and its output is available.

MalformedInput

MalformedInput

Text is not exactly canonical 8-4-4-4-12 hexadecimal, or an input has the wrong size.

NilIdentity

NilIdentity

The value is nil but the policy requires an actual identity.

UnsupportedVersion

UnsupportedVersion

The variant is RFC 9562 but the version is not 4.

UnsupportedVariant

UnsupportedVariant

The variant field is not the RFC 9562 variant.

InsufficientSpace

InsufficientSpace

The caller's buffer cannot hold UUID_TEXT_LENGTH characters.

EntropyUnavailable

EntropyUnavailable

The entropy source is missing or could not supply bytes.

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

Aliases

AssetId

using ludus::foundation::identity::AssetId = TypedUuid<AssetTag>

One logical authored asset. Survives moving the file or changing its contents.

Related types: AssetTag · TypedUuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

SourceObjectId

using ludus::foundation::identity::SourceObjectId = TypedUuid<SourceObjectTag>

One authored object in a level or reusable source document, retained through edits and renames.

Related types: SourceObjectTag · TypedUuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

InstanceId

using ludus::foundation::identity::InstanceId = TypedUuid<InstanceTag>

One placement or saved instance scope; distinguishes repeated instances of one source.

Related types: InstanceTag · TypedUuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

Constants and variables

FIRST_GENERATION

constexpr uint32 ludus::foundation::identity::FIRST_GENERATION = 1

First generation a registry assigns to a slot. Generation zero is never issued.

Related types: uint32

Declared in modules/foundation/identity/include/ludus/foundation/identity/handle.hpp

TERMINAL_GENERATION

constexpr uint32 ludus::foundation::identity::TERMINAL_GENERATION = ~uint32{0}

Last usable generation of a slot. Releasing a slot at this generation retires it.

Related types: uint32

Declared in modules/foundation/identity/include/ludus/foundation/identity/handle.hpp

LAST_LIFETIME_ID

constexpr uint64 ludus::foundation::identity::LAST_LIFETIME_ID = ~uint64{0} - 1

Largest token the process source can issue. After it, issuance reports IdentityExhausted.

Related types: uint64

Declared in modules/foundation/identity/include/ludus/foundation/identity/lifetime.hpp

UUID_BYTE_COUNT

constexpr usize ludus::foundation::identity::UUID_BYTE_COUNT = 16

Number of bytes in a UUID's canonical binary form.

Related types: usize

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_TEXT_LENGTH

constexpr usize ludus::foundation::identity::UUID_TEXT_LENGTH = 36

Number of characters in canonical 8-4-4-4-12 UUID text, without a terminator.

Related types: usize

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_TEXT_BUFFER_BYTES

constexpr usize ludus::foundation::identity::UUID_TEXT_BUFFER_BYTES = UUID_TEXT_LENGTH + 1

Buffer size that holds canonical UUID text and a terminating zero.

Related types: usize

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_VERSION_RANDOM

constexpr uint8 ludus::foundation::identity::UUID_VERSION_RANDOM = 4

RFC 9562 version number of random UUIDs, the only version accepted for durable identity.

Related types: uint8

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_VERSION_BYTE_INDEX

constexpr usize ludus::foundation::identity::UUID_VERSION_BYTE_INDEX = 6

Index of the byte whose high nibble holds the RFC 9562 version field.

Related types: usize

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_VARIANT_BYTE_INDEX

constexpr usize ludus::foundation::identity::UUID_VARIANT_BYTE_INDEX = 8

Index of the byte whose high bits hold the RFC 9562 variant field.

Related types: usize

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_VARIANT_MASK

constexpr uint8 ludus::foundation::identity::UUID_VARIANT_MASK = 0xC0

Mask selecting the two variant bits of the variant byte.

Related types: uint8

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

UUID_STANDARD_VARIANT_BITS

constexpr uint8 ludus::foundation::identity::UUID_STANDARD_VARIANT_BITS = 0x80

Variant bits 10 of RFC 9562 UUIDs, positioned within UUID_VARIANT_MASK.

Related types: uint8

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

Functions

AdvanceGeneration

LUDUS_INLINE constexpr GenerationStatus ludus::foundation::identity::AdvanceGeneration(uint32 &inoutGeneration) noexcept

Advance the generation of a slot that is being released.

Registries call this when a slot's current incarnation ends, before the slot can be reused. A slot whose generation reaches TERMINAL_GENERATION is retired instead of wrapping, so a stale handle can never name a later incarnation of the same owner. Retired slots still count against the registry's capacity.

Parameter	Description
inoutGeneration	The released incarnation's generation; incremented only when the result is GenerationStatus::Advanced.

Returns

Advanced, Retired, or InvalidGeneration for a zero input.

Related types: uint32 · GenerationStatus

Declared in modules/foundation/identity/include/ludus/foundation/identity/handle.hpp

TryIssueLifetimeId

LifetimeIdStatus ludus::foundation::identity::TryIssueLifetimeId(uint64 &outLifetimeId) noexcept

Issue a fresh nonzero owner token for one new registry lifetime.

Tokens are process-unique and monotonically increasing from 1. A registry obtains one token when it is initialized and stores it as the Owner of every handle it issues; clearing and rebuilding a registry obtains a new token rather than resetting generations under the old one. Tokens identify a lifetime, not an address, thread, name or content revision, and are never serialized.

Thread-safe and lock-free; uses a relaxed atomic counter, so a token establishes uniqueness only. Publishing the registry that owns it needs separate synchronization. No allocation.

Parameter	Description
outLifetimeId	Receives the token on success; unchanged on exhaustion.

Returns

Success, or IdentityExhausted once LAST_LIFETIME_ID has been issued.

Warning

The counter lives in this static library. Each executable or shared module that links it privately receives its own counter, which is not process-wide issuance. Reloadable gameplay modules must obtain tokens from the host rather than calling this function from their own copy.

Related types: uint64 · LifetimeIdStatus

Declared in modules/foundation/identity/include/ludus/foundation/identity/lifetime.hpp

ValidateUuid

UuidStatus ludus::foundation::identity::ValidateUuid(const Uuid &value, UuidPolicy policy) noexcept

Check a decoded value against a policy.

Use this after reading 16 canonical bytes from a versioned binary format.

Returns

Success, NilIdentity, UnsupportedVariant or UnsupportedVersion.

Related types: UuidPolicy · UuidStatus · Uuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

TryParseUuid

UuidStatus ludus::foundation::identity::TryParseUuid(const char *text, usize size, UuidPolicy policy, Uuid &outValue) noexcept

Parse canonical UUID text.

The complete input must be exactly 36 characters: hexadecimal digits in groups of 8-4-4-4-12 separated by -. Digits are case-insensitive. Whitespace, braces, urn:uuid: prefixes, missing or extra separators and terminators inside size are rejected. The decoded value is then checked with ValidateUuid(). No allocation; uses no shared state.

Parameter	Description
text	Input characters; may be null only when size is zero.
size	Number of characters to parse.
policy	Which decoded values are accepted.
outValue	Receives the value on Success; unchanged on any failure.

Returns

Success, MalformedInput, or a ValidateUuid() failure.

Related types: usize · UuidPolicy · UuidStatus · Uuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

FormatUuid

UuidStatus ludus::foundation::identity::FormatUuid(const Uuid &value, char *text, usize capacity) noexcept

Format a UUID as canonical lowercase 8-4-4-4-12 text.

Writes exactly UUID_TEXT_LENGTH characters. When capacity is at least UUID_TEXT_BUFFER_BYTES, a terminating zero follows them. Any 16 bytes format; formatting does not validate the version. No allocation.

Parameter	Description
value	UUID to format.
text	Destination; may be null only when capacity is zero.
capacity	Size of the destination in bytes.

Returns

Success, or InsufficientSpace with the destination untouched.

Related types: usize · UuidStatus · Uuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

TryMakeUuidV4

UuidStatus ludus::foundation::identity::TryMakeUuidV4(const uint8 *randomBytes, usize size, Uuid &outValue) noexcept

Build a version-4 UUID from exactly 16 random bytes.

Pure construction: sets the version and variant fields and keeps the other 122 bits. The caller is responsible for the bytes coming from a cryptographically secure source; never pass wall time, addresses or a gameplay PRNG. Production code uses TryGenerateUuidV4().

Parameter	Description
randomBytes	Input bytes; may be null only when size is zero.
size	Number of bytes; must equal UUID_BYTE_COUNT.
outValue	Receives the UUID on Success; unchanged on failure.

Returns

Success, or MalformedInput for a wrong size.

Related types: uint8 · usize · UuidStatus · Uuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp

TryGenerateUuidV4

UuidStatus ludus::foundation::identity::TryGenerateUuidV4(const EntropySource &source, Uuid &outValue) noexcept

Generate a fresh version-4 UUID from an entropy source.

Obtains 16 bytes with one call to the source, then applies TryMakeUuidV4(). Global uniqueness is probabilistic: owners of a project, save or package index must still check the new value against that index before publishing it.

Parameter	Description
source	Entropy provider; a null FillBytesOrNull is reported as unavailable.
outValue	Receives the UUID on Success; unchanged when entropy fails, with no partial output.

Returns

Success or EntropyUnavailable.

Related types: UuidStatus · EntropySource · Uuid

Declared in modules/foundation/identity/include/ludus/foundation/identity/uuid.hpp