Enum ResourceState

Enum Documentation

enum class portal::ResourceState : uint8_t

Represents the current state of a resource reference in its loading lifecycle.

The resource system uses a state machine to track whether a resource is ready for use. ResourceReference<T> instances query their state to determine if the underlying resource has finished loading, is still pending, or encountered an error.

State Transitions: 

Unknown → Pending → Loaded
        ↘       ↘ Error
        ↘ Missing
        ↘ Null
States are monotonic - once a reference reaches a terminal state (Loaded, Error, Missing, Null), it never changes. The Pending state indicates active loading on the job system.

Thread Safety: State queries from ResourceReference are thread-safe. The registry uses internal locking to ensure state transitions are atomic.

Usage: 

auto texture_ref = registry.load<TextureResource>(STRING_ID("textures/albedo.png"));

// Poll the state (non-blocking)
switch (texture_ref.get_state()) {
    case ResourceState::Loaded:
        // Resource ready to use
        auto& texture = texture_ref.get();
        break;
    case ResourceState::Pending:
        // Still loading, check again next frame
        break;
    case ResourceState::Error:
        // Load failed, handle error
        LOG_ERROR("Failed to load texture");
        break;
    case ResourceState::Missing:
        // Resource not found in database
        LOG_ERROR("Texture not found");
        break;
}

See also

ResourceReference::get_state() for how references query their current state

See also

ResourceRegistry::get_resource() for the underlying state lookup

Note

Resources themselves cannot have an invalid state - only references can be invalid. Once a resource is loaded into the registry, it’s always valid.

Values:

enumerator Unknown

Initial state for references that haven’t queried the registry yet.

When a ResourceReference is first created by load(), it starts in Unknown state. The first call to get_state() or is_valid() will query the registry and transition to the actual state (Pending, Loaded, Missing, or Error).

enumerator Loaded

Resource is fully loaded and ready for use.

Terminal state. The resource has been successfully loaded from disk/memory, processed by the appropriate loader, and stored in the registry. Calling get() on a reference in this state will return a valid resource pointer.

Note

This is the only state where get() is guaranteed to succeed without blocking.

enumerator Missing

Resource was not found in the resource database.

Terminal state. The requested resource_id doesn’t exist in the database’s metadata. This typically means the file doesn’t exist in the scanned resource directories, or the database hasn’t been refreshed after adding new files.

enumerator Pending

Resource is currently being loaded on the job system.

Transient state. A background job is actively loading this resource. The job may be:

  • Reading bytes from disk via ResourceSource

  • Decoding the file format (PNG, GLTF, etc.)

  • Uploading data to GPU memory

  • Creating sub-resources for composite types

References should check again later (typically next frame) to see if loading completed.

Note

For immediate_load(), this state is never observable since the call blocks.

enumerator Error

Resource loading failed due to an error.

Terminal state. The loader encountered an error during loading, such as:

  • Corrupted file data

  • Unsupported file format variant

  • Out of memory

  • GPU resource allocation failure

Check application logs for detailed error messages from the loader.

enumerator Null

Special state for default-constructed or null references.

Terminal state. Indicates a reference created with INVALID_STRING_ID or moved-from. Calling get() on a Null reference is undefined behavior - always check is_valid() first.

Note

This state is distinct from Missing - Null means the reference itself is invalid, while Missing means a valid reference couldn’t find its resource.