async_loader.h File Reference

Threaded asynchronous file loader engine (Format-agnostic). More...

#include "asset_manager.h"
#include "gl_common.h"
#include <stdbool.h>
#include <stdint.h>
#include "app_subsystem.h"

Include dependency graph for async_loader.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	AsyncRequest
	Données de la requête asynchrone transférées entre les threads. More...

Macros
#define	ASYNC_MAX_PATH   256
#define	APP_ASYNC_LOADER_DESCRIPTOR    {"async_loader", async_loader_subsys_init, async_loader_subsys_cleanup}

Enumerations
enum	AsyncState {   ASYNC_IDLE = 0 , ASYNC_PENDING , ASYNC_LOADING , ASYNC_WAITING_FOR_PBO ,   ASYNC_CONVERTING , ASYNC_READY , ASYNC_FAILED }

Functions
AsyncLoader *	async_loader_create (struct TracyManager *mgr)
	Initialize the asynchronous loader subsystem.
void	async_loader_destroy (AsyncLoader *loader)
	Tear down the asynchronous loader subsystem.
bool	async_loader_request (AsyncLoader *loader, const AssetHandle *asset)
	Request a new asset to be loaded asynchronously.
bool	async_loader_poll (AsyncLoader *loader, AsyncRequest *out_req)
	Poll the status of the current request.
void	async_loader_provide_pbo (AsyncLoader *loader, void *mapped_ptr, GLuint pbo_id)
	Provide the mapped memory address and GL buffer ID for PBO writing.
void	async_loader_cancel (AsyncLoader *loader)
	Cancel a loading request waiting for PBO input.
int	async_loader_subsys_init (struct App *app)
void	async_loader_subsys_cleanup (struct App *app)

Detailed Description

Threaded asynchronous file loader engine (Format-agnostic).

Macro Definition Documentation

APP_ASYNC_LOADER_DESCRIPTOR

#define APP_ASYNC_LOADER_DESCRIPTOR    {"async_loader", async_loader_subsys_init, async_loader_subsys_cleanup}

ASYNC_MAX_PATH

#define ASYNC_MAX_PATH   256

Enumeration Type Documentation

AsyncState

enum AsyncState

Enumerator
ASYNC_IDLE	No active request.
ASYNC_PENDING	Request submitted but not yet picked up by worker.
ASYNC_LOADING	Worker is loading/decompressing file
ASYNC_WAITING_FOR_PBO	Worker waiting for PBO from main thread
ASYNC_CONVERTING	Worker converting floats to mapped PBO
ASYNC_READY	Data is ready in PBO (or half_data if fallback)
ASYNC_FAILED	Loading failed

Function Documentation

async_loader_cancel()

void async_loader_cancel

(

AsyncLoader *

loader

)

Cancel a loading request waiting for PBO input.

Aborts the current request if it is still waiting for the main thread to provide a PBO.

Parameters

loader

Loader instance.

State transitions:

• Expected Input State: ASYNC_WAITING_FOR_PBO.
• On success: Transits to ASYNC_FAILED, signals the worker thread to cleanup.
• If called in any other state (e.g. ASYNC_CONVERTING): Ignored to prevent data corruption.

Concurrency: Thread-safe. Acquires request_mutex.

async_loader_create()

AsyncLoader * async_loader_create

(

struct TracyManager *

mgr

)

Initialize the asynchronous loader subsystem.

Allocates resources, initializes synchronization primitives (mutex, condvar), and spawns the background worker thread.

Parameters

mgr	Tracy profiler manager instance.

Returns

A new AsyncLoader instance on success, NULL on failure.

Concurrency: Thread-safe. Lock initialized inside. Initial state: ASYNC_IDLE.

Here is the call graph for this function:

async_loader_destroy()

void async_loader_destroy

(

AsyncLoader *

loader

)

Tear down the asynchronous loader subsystem.

Signals the worker thread to exit, waits for its completion (joins it), releases any pending resources/requests, and destroys synchronization primitives.

Parameters

loader

Loader instance to destroy. Can be NULL (no-op).

Concurrency: Safe to call from the main thread during cleanup. Post-condition: Mutex/condvar are destroyed and memory is freed.

Here is the call graph for this function:

async_loader_poll()

bool async_loader_poll	(	AsyncLoader *	loader,
		AsyncRequest *	out_req
	)

Poll the status of the current request.

Checks if the request is ready for GPU upload, waiting for PBO allocation, or has failed. This is meant to be called periodically from the main thread.

Parameters

loader	Loader instance.
out_req	Destination structure to copy the request snapshot if ready/waiting.

Returns

true if a state transition needs handling (READY, WAITING_FOR_PBO, FAILED), false otherwise.

State transitions:

• Expected Input State: Any state.
• If current state is ASYNC_READY: Copies request, resets state to ASYNC_IDLE, returns true.
• If current state is ASYNC_FAILED: Copies request, resets state to ASYNC_IDLE, returns true.
• If current state is ASYNC_WAITING_FOR_PBO: Copies request, state remains ASYNC_WAITING_FOR_PBO, returns true.
• For any other state: Returns false (no action needed yet).

Concurrency: Thread-safe. Acquires request_mutex.

async_loader_provide_pbo()

void async_loader_provide_pbo	(	AsyncLoader *	loader,
		void *	mapped_ptr,
		GLuint	pbo_id
	)

Provide the mapped memory address and GL buffer ID for PBO writing.

Called by the main thread after detecting ASYNC_WAITING_FOR_PBO during poll. Maps the CPU pointer to the PBO and allows the worker to perform the conversion.

Parameters

loader	Loader instance.
mapped_ptr	Pointer to the mapped buffer memory (CPU visible).
pbo_id	OpenGL buffer object ID (or 0 for CPU-only malloc fallback).

State transitions:

• Expected Input State: ASYNC_WAITING_FOR_PBO.
• On success: Transits to ASYNC_CONVERTING, signals the worker thread to resume.
• If called in any other state: Ignored (no-op).

Concurrency: Thread-safe. Acquires request_mutex.

async_loader_request()

bool async_loader_request	(	AsyncLoader *	loader,
		const AssetHandle *	asset
	)

Request a new asset to be loaded asynchronously.

Accepts a loading task if the loader is idle or finished with the previous one.

Parameters

loader	Loader instance.
asset	Path and format metadata of the asset.

Returns

true if the request was accepted, false if the loader was busy or invalid.

State transitions:

• Expected Input State: ASYNC_IDLE, ASYNC_FAILED, or ASYNC_READY.
• On success: Transits to ASYNC_PENDING, signals the worker thread.
• On failure: State remains unchanged (loader is currently busy: ASYNC_LOADING, ASYNC_WAITING_FOR_PBO, ASYNC_CONVERTING).

Concurrency: Thread-safe. Acquires request_mutex.

Here is the call graph for this function:

async_loader_subsys_cleanup()

void async_loader_subsys_cleanup

(

struct App *

app

)

Here is the call graph for this function:

async_loader_subsys_init()

int async_loader_subsys_init

(

struct App *

app

)

Here is the call graph for this function: