Struct Handle 

pub struct Handle<T> { /* private fields */ }

A type-safe, generation-counted handle to an engine resource.

Handles are lightweight (8 bytes) identifiers that can be safely passed across FFI boundaries. The generic type parameter T provides compile-time type safety, ensuring handles for different resource types cannot be mixed.

FFI Safety

The #[repr(C)] attribute ensures this struct has a predictable memory layout for interoperability with C#, Python, and other languages:

• Offset 0: index (4 bytes, u32)
• Offset 4: generation (4 bytes, u32)
• Total size: 8 bytes, alignment: 4 bytes

The PhantomData<T> is a zero-sized type that doesn’t affect the layout.

Implementations

impl<T> Handle<T>

pub const INVALID: Self

The invalid handle constant.

Used to represent “no resource” or “null handle”. This is distinguishable from any valid handle because:

• index is u32::MAX, which exceeds any reasonable allocation count
• generation is 0, which is never used for valid allocations

Example

use goud_engine::core::handle::Handle;

struct Texture;

let handle: Handle<Texture> = Handle::INVALID;
assert!(!handle.is_valid());
assert_eq!(handle.index(), u32::MAX);
assert_eq!(handle.generation(), 0);

pub const fn new(index: u32, generation: u32) -> Self

Creates a new handle with the given index and generation.

This is typically called by HandleAllocator, not by user code. Users should obtain handles through the allocator or storage APIs.

Arguments

• index - The slot index in the storage array
• generation - The generation counter for this slot

Example

use goud_engine::core::handle::Handle;

struct Shader;

let handle: Handle<Shader> = Handle::new(42, 3);
assert_eq!(handle.index(), 42);
assert_eq!(handle.generation(), 3);

pub const fn index(&self) -> u32

Returns the index component of this handle.

The index is the slot number in the allocator/storage. It identifies which entry the handle refers to.

Example

use goud_engine::core::handle::Handle;

struct Mesh;

let handle: Handle<Mesh> = Handle::new(10, 1);
assert_eq!(handle.index(), 10);

pub const fn generation(&self) -> u32

Returns the generation component of this handle.

The generation is incremented each time a slot is deallocated and reused. It prevents use-after-free by invalidating old handles.

Example

use goud_engine::core::handle::Handle;

struct Audio;

let handle: Handle<Audio> = Handle::new(5, 7);
assert_eq!(handle.generation(), 7);

pub const fn is_valid(&self) -> bool

Checks if this handle is valid (not the INVALID sentinel).

A handle is considered valid if it is not equal to Handle::INVALID. Note that a “valid” handle here only means it’s not the null sentinel; it may still refer to a deallocated resource (stale handle).

To check if a handle refers to a live resource, use the allocator’s is_alive() method.

Example

use goud_engine::core::handle::Handle;

struct Sprite;

let valid: Handle<Sprite> = Handle::new(0, 1);
assert!(valid.is_valid());

let invalid: Handle<Sprite> = Handle::INVALID;
assert!(!invalid.is_valid());

pub const fn to_u64(&self) -> u64

Packs this handle into a single u64 value.

The packed format is:

• Upper 32 bits: generation
• Lower 32 bits: index

This is useful for FFI with languages that prefer a single integer over a struct, and for use as hash map keys.

Example

use goud_engine::core::handle::Handle;

struct Resource;

let handle: Handle<Resource> = Handle::new(42, 7);
let packed = handle.to_u64();
let unpacked: Handle<Resource> = Handle::from_u64(packed);

assert_eq!(handle, unpacked);

pub const fn from_u64(packed: u64) -> Self

Creates a handle from a packed u64 value.

This is the inverse of to_u64(). The packed format is:

• Upper 32 bits: generation
• Lower 32 bits: index

Example

use goud_engine::core::handle::Handle;

struct Resource;

let packed: u64 = (7u64 << 32) | 42u64;  // gen=7, index=42
let handle: Handle<Resource> = Handle::from_u64(packed);

assert_eq!(handle.index(), 42);
assert_eq!(handle.generation(), 7);

Trait Implementations

impl<T> Clone for Handle<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Handle<T>

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

Formats the value using the given formatter.

impl<T> Default for Handle<T>

fn default() -> Self

Returns Handle::INVALID.

The default handle is the invalid sentinel, representing “no resource”. This is useful for struct initialization where a handle field may not yet have a valid value.

Example

use goud_engine::core::handle::Handle;

struct Texture;

let handle: Handle<Texture> = Default::default();
assert!(!handle.is_valid());
assert_eq!(handle, Handle::INVALID);

impl<T> From<Handle<T>> for u64

fn from(handle: Handle<T>) -> u64

Converts a handle to its packed u64 representation.

Format: upper 32 bits = generation, lower 32 bits = index.

impl<T> From<u64> for Handle<T>

fn from(packed: u64) -> Self

Creates a handle from a packed u64 representation.

Format: upper 32 bits = generation, lower 32 bits = index.

impl<T> Hash for Handle<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> PartialEq for Handle<T>

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T> Copy for Handle<T>

impl<T> Eq for Handle<T>