ResourceManager is a singleton that manages all resources in the game. It provides a way to load, reload, and unload resources. 更多...

#include <Resource.h>

类 eve::ResourceManager 继承关系图:

类
struct	AsyncLoad
	AsyncLoad public API. 更多...

Public 成员函数
Resource *	get (std::string key)
	Get the cached resource for `key`; on a miss, load it through the registered IAssetReloader providers and cache the result.

eve::Result< void >	request (std::string key)
	Queue a cache miss load without blocking for decode to finish.

eve::Result< void >	requestAll (std::span< const std::string > keys)
	`request()` every key; stops at the first hard failure.

OptionalRef< Resource >	peek (const std::string &key)
	Cache lookup that never starts a load.

eve::Result< ResourcePin >	pin (Resource *resource)
	Keeps one cached resource alive across unload()/clear()/reload.

ResultRef< Resource >	waitFor (std::string key)
	Block until `key` is cached, failed, or unclaimed.

size_t	pendingCount () const
	Number of in-flight `request()` jobs (including failed-not-yet-consumed).

void	unload (std::string key)
	Drop the exact cache entry `key` (parameters included). The resource stays alive while other holders still reference it.

void	unloadPath (const std::string &path)
	Drop every cache entry whose path matches, whatever its parameters.

size_t	count () const
	Number of cached entries.

void	clear ()
	Drop every entry and re-arm lazy registration (tests / teardown).

const char *	reloadKind () const override
	Stable capability name for the cache reloader.

bool	handlesPath (const std::string &normPath) const override
	Handles path.

eve::Result< bool >	reload (const std::string &normPath) override
	Reloads .

Resource *	load (const std::string &key) override
	Cache provider entry point; this implementation does not claim keys.

Public 成员函数继承自 eve::caps::IAssetReloader
virtual	~IAssetReloader ()=default

静态 Public 成员函数
static ResourceManager &	getInstance ()
	Returns the instance.

static std::string	normalizePath (std::string path)
	Normalize a VFS path: backslashes to '/', strip leading "./" and trailing '/'.

static std::string	makeKey (const std::string &path, const std::string &query="")
	Build a cache key from a path and optional `?query` parameters.

static std::string	pathOfKey (const std::string &key)
	The path part of a cache key (everything before the first '?').

Protected 类型
using	ResourceRef = script::RuntimeHandleRef< ResourceCacheTag >

Protected 成员函数
	ResourceManager ()=default
	Resource manager.

void	ensureRegistered ()
	Ensure registered.

Resource *	loadReplacement (const std::string &key)
	Loads replacement.

Resource *	loadUncached (const std::string &norm)
	Loads uncached.

void	runLoadJob (std::string norm, uint64_t epoch)
	Run load job.

Resource *	borrowLocked (const ResourceRef &reference)
	Borrows the live resource behind a cache entry.

Protected 属性
script::RuntimeObjectRegistry< Resource, ResourceCacheTag >	registry_
	Registry that exclusively owns every cached resource.

std::map< std::string, ResourceRef >	resources

std::unordered_map< std::string, std::shared_ptr< AsyncLoad > >	pending_

std::mutex	mu_

std::condition_variable	cv_

uint64_t	epoch_ = 1

bool	registered_ = false

额外继承的成员函数
Public 类型继承自 eve::caps::IAssetReloader
enum	Priority { kCache = 0 , kTexture = 10 , kConsumer = 20 }
	Priority public API. 更多...

静态 Public 属性继承自 eve::caps::IAssetReloader
static constexpr const char *	capabilityName = "IAssetReloader"

详细描述

ResourceManager is a singleton that manages all resources in the game. It provides a way to load, reload, and unload resources.

The manager is a unified cache for CPU-side assets (ImageData, FontData, ModelData, SoundData, ...). Keys are normalized VFS paths, optionally with ?param=value entries ("fonts/a.ttf?size=16"). On a miss it asks the registered eve::caps::IAssetReloader providers which one claims the key and can load() it; the first hit is cached and returned. On a file change the manager itself participates in hot reload as the first IAssetReloader listener (kCache priority): every cached entry for that path is re-loaded and refreshed in place through Resource::adopt, so holders keep a valid pointer. Entries that list the refreshed resource as a dependency are refreshed too (transitively, cycle-safe).

The cache itself is thread-safe: map access is mutex-guarded and the heavy provider load() runs outside the lock, so sceneloader's background decode threads can insert entries while the main thread reads them. Reloads (adopt) are expected on the main thread during hot-reload dispatch.

request() / waitFor() are the asynchronous programming interface: request queues CPU decode on caps::IAsyncWorkExecutor (the thread module) and waitFor joins that job. get() waits for an in-flight request of the same key so a prefetch cannot race a later synchronous load into a double decode.

在文件 Resource.h 第 152 行定义.

成员类型定义说明

◆ ResourceRef

using eve::ResourceManager::ResourceRef = script::RuntimeHandleRef<ResourceCacheTag>

protected

在文件 Resource.h 第 322 行定义.

构造及析构函数说明

◆ ResourceManager()

eve::ResourceManager::ResourceManager ( )

protecteddefault

Resource manager.

被这些函数引用 getInstance().

成员函数说明

◆ borrowLocked()

Resource * eve::ResourceManager::borrowLocked ( const ResourceRef & reference )

inlineprotected

Borrows the live resource behind a cache entry.

参数

reference Entry from resources.

返回: The owned resource, or null when the entry is stale.

备注: Callers must hold mu_; the borrowed pointer is only valid until the next cache mutation.

在文件 Resource.h 第 331 行定义.

引用了 reference.

被这些函数引用 peek(), pin(), reload() , 以及 waitFor().

◆ clear()

void eve::ResourceManager::clear ( )

Drop every entry and re-arm lazy registration (tests / teardown).

在文件 Resource.cpp 第 360 行定义.

引用了 cv_, epoch_, mu_, pending_, registered_, registry_ , 以及 resources.

◆ count()

size_t eve::ResourceManager::count ( ) const

Number of cached entries.

在文件 Resource.cpp 第 58 行定义.

引用了 mu_ , 以及 resources.

被这些函数引用 eve::dev::resourceCacheCount().

◆ ensureRegistered()

void eve::ResourceManager::ensureRegistered ( )

protected

Ensure registered.

在文件 Resource.cpp 第 51 行定义.

引用了 eve::caps::IAssetReloader::kCache, mu_ , 以及 registered_.

被这些函数引用 getInstance(), request() , 以及 waitFor().

◆ get()

Resource * eve::ResourceManager::get ( std::string key )

Get the cached resource for key; on a miss, load it through the registered IAssetReloader providers and cache the result.

参数

key	A normalized VFS path, optionally with `?params`.

返回: The shared resource, or nullptr when no provider claims the key. Loader errors propagate to the caller. The returned pointer is owned by the cache (kept alive while the entry exists); callers must not delete it, and it stays valid until unload() or process exit. @ownership Borrowed from the cache; ResourceManager is the owning authority. @nullable Yes when no registered provider claims key. @lifetime Valid while the cache entry remains loaded and until manager teardown; callers must not retain it across unload or reload replacement. @thread Lookup may be called by concurrent readers; cache mutation and reload commit are serialized by ResourceManager. @reentrancy The returned resource must not be used to re-enter cache mutation while a ResourceManager operation is holding its internal lock.

在文件 Resource.cpp 第 141 行定义.

引用了 detail, key, eve::NotFound , 以及 waitFor().

被这些函数引用 eve::font::Font::newFontDataFromFile(), eve::image::Image::newImageDataFromFile(), eve::model3d::Model3D::newModelDataFromFile() , 以及 eve::sound::Sound::newSoundDataFromFile().

◆ getInstance()

ResourceManager & eve::ResourceManager::getInstance ( )

static

Returns the instance.

在文件 Resource.cpp 第 15 行定义.

引用了 ensureRegistered() , 以及 ResourceManager().

被这些函数引用 eve::Resource::addDependency(), eve::sceneloader::SceneLoader::diff(), eve::graphics::Graphics::ensureFileTexturesReady(), eve::font::Font::newFontDataFromFile(), eve::image::Image::newImageDataFromFile(), eve::model3d::Model3D::newModelDataFromFile(), eve::sound::Sound::newSoundDataFromFile(), eve::graphics::vulkan::Graphics::newTextureFromFile(), eve::graphics::webgpu::Graphics::newTextureFromFile(), eve::filesystem::readPreparedFile(), eve::graphics::vulkan::Graphics::reloadTextureFromFile(), eve::graphics::webgpu::Graphics::reloadTextureFromFile(), eve::graphics::Graphics::requestFileImageDecode(), eve::model3d::Model3D::requestModelData(), eve::filesystem::requestPreparedFile() , 以及 eve::dev::resourceCacheCount().

◆ handlesPath()

bool eve::ResourceManager::handlesPath ( const std::string & normPath ) const

overridevirtual

Handles path.

实现了 eve::caps::IAssetReloader.

在文件 Resource.cpp 第 380 行定义.

引用了 mu_, normalizePath(), pathOfKey() , 以及 resources.

◆ load()

Resource * eve::ResourceManager::load ( const std::string & key )

inlineoverridevirtual

Cache provider entry point; this implementation does not claim keys.

返回: Always nullptr for the cache provider. @ownership Borrowed/null; no resource is created by this override. @nullable Yes. @lifetime No returned object; the call is main-thread affine during reload dispatch. @thread Main/reload dispatch thread. @reentrancy Does not invoke external callbacks.

重载 eve::caps::IAssetReloader .

在文件 Resource.h 第 296 行定义.

◆ loadReplacement()

Resource * eve::ResourceManager::loadReplacement ( const std::string & key )

protected

Loads replacement.

在文件 Resource.cpp 第 496 行定义.

引用了 key , 以及 loadUncached().

被这些函数引用 reload().

◆ loadUncached()

Resource * eve::ResourceManager::loadUncached ( const std::string & norm )

protected

Loads uncached.

在文件 Resource.cpp 第 63 行定义.

引用了 r , 以及 eve::Resource::setUri().

被这些函数引用 loadReplacement(), runLoadJob() , 以及 waitFor().

◆ makeKey()

std::string eve::ResourceManager::makeKey	(	const std::string &	path,
		const std::string &	query = `""`
	)

static

Build a cache key from a path and optional ?query parameters.

在文件 Resource.cpp 第 37 行定义.

引用了 key, normalizePath() , 以及 path.

被这些函数引用 eve::model3d::modelCacheKey(), eve::font::Font::newFontDataFromFile(), peek(), request(), unload() , 以及 waitFor().

◆ normalizePath()

std::string eve::ResourceManager::normalizePath ( std::string path )

static

Normalize a VFS path: backslashes to '/', strip leading "./" and trailing '/'.

在文件 Resource.cpp 第 28 行定义.

引用了 c , 以及 path.

被这些函数引用 handlesPath(), makeKey(), pathOfKey(), reload() , 以及 unloadPath().

◆ pathOfKey()

std::string eve::ResourceManager::pathOfKey ( const std::string & key )

static

The path part of a cache key (everything before the first '?').

在文件 Resource.cpp 第 46 行定义.

引用了 key, normalizePath() , 以及 q.

被这些函数引用 handlesPath(), reload() , 以及 unloadPath().

◆ peek()

OptionalRef< Resource > eve::ResourceManager::peek ( const std::string & key )

Cache lookup that never starts a load.

返回: Empty when missing or still decoding; borrowed cache entry otherwise. @ownership Borrowed from the cache. @nullable Yes — empty optional means not ready. @lifetime Valid until unload/clear of that entry; do not retain across reload. @thread Concurrent readers are serialized with the cache mutex.

在文件 Resource.cpp 第 216 行定义.

引用了 borrowLocked(), key, makeKey(), mu_ , 以及 resources.

◆ pendingCount()

size_t eve::ResourceManager::pendingCount ( ) const

Number of in-flight request() jobs (including failed-not-yet-consumed).

在文件 Resource.cpp 第 327 行定义.

引用了 mu_ , 以及 pending_.

◆ pin()

eve::Result< ResourcePin > eve::ResourceManager::pin ( Resource * resource )

Keeps one cached resource alive across unload()/clear()/reload.

参数

resource Borrowed pointer to a resource the cache owns, typically one returned by get()/peek()/waitFor() or a newXFromFile() factory. A null or already-stale pointer is rejected; this call never dereferences it, so a concurrent unload() cannot make the call itself read freed memory.

返回: A move-only keep-alive pin, or NotFound when no live cache entry resolves to resource (already unloaded, or never cached here). Once a pin is returned it is the authority: use pin.get() rather than the borrowed pointer, which may have been stale before the call. @ownership The cache keeps owning the resource; the pin only postpones its destruction, so the address stays valid after unload() drops the cache entry (this is what keeps a playing SoundData alive). @lifetime The pin must not outlive the manager; release it (or let it go out of scope) as soon as the borrower no longer needs the resource. @cost O(cached entries): the entry is located by address. @thread Same serialization as the rest of the cache. @reentrancy Does not invoke callbacks.

在文件 Resource.cpp 第 311 行定义.

引用了 borrowLocked(), eve::Diagnostic::error(), eve::Result< T >::failure(), eve::InvalidArgument, mu_, eve::NotFound, registry_, resource , 以及 resources.

被这些函数引用 eve::Resource::addDependency(), eve::graphics::vulkan::Graphics::reloadTextureFromFile() , 以及 eve::graphics::webgpu::Graphics::reloadTextureFromFile().

◆ reload()

eve::Result< bool > eve::ResourceManager::reload ( const std::string & normPath )

overridevirtual

Reloads .

实现了 eve::caps::IAssetReloader.

在文件 Resource.cpp 第 390 行定义.

引用了 eve::Applied, borrowLocked(), eve::Resource::getDependencies(), key, loadReplacement(), mu_, normalizePath(), pathOfKey(), pinned, registry_, resources, eve::Status::success() , 以及 eve::Result< T >::success().

被这些函数引用 eve::sceneloader::SceneLoader::diff().

◆ reloadKind()

const char * eve::ResourceManager::reloadKind ( ) const

inlineoverridevirtual

Stable capability name for the cache reloader.

返回: Borrowed, non-null, null-terminated static text. @ownership Borrowed; not allocated and not caller-owned. @nullable No. @lifetime Static for the process lifetime. @thread Thread-safe and side-effect free. @reentrancy Does not invoke callbacks.

实现了 eve::caps::IAssetReloader.

在文件 Resource.h 第 281 行定义.

◆ request()

eve::Result< void > eve::ResourceManager::request ( std::string key )

Queue a cache miss load without blocking for decode to finish.

参数

key	Normalized VFS path, optionally with `?params`.

返回: NoOp if already cached, Pending if a load is already in flight, Applied if this call queued or completed a load, NotFound if no provider claims the key, or Failed when inline load throws. @ownership Does not transfer a resource; the cache remains the owner. @lifetime The pending job keeps the key alive until waitFor/get/clear. @thread Safe to call from the game thread. Decode runs on a worker when IAsyncWorkExecutor is registered, otherwise inline. @reentrancy Must not be called from IAssetReloader::load().

在文件 Resource.cpp 第 149 行定义.

引用了 eve::Applied, cv_, ensureRegistered(), epoch, epoch_, eve::Diagnostic::error(), eve::Failed, eve::Result< T >::failure(), eve::InvalidArgument, key, makeKey(), mu_, eve::NoOp, eve::NotFound, eve::Pending, pending_, r, resources, runLoadJob(), eve::Status::success() , 以及 eve::Result< T >::success().

被这些函数引用 eve::graphics::Graphics::requestFileImageDecode(), eve::model3d::Model3D::requestModelData() , 以及 eve::filesystem::requestPreparedFile().

◆ requestAll()

eve::Result< void > eve::ResourceManager::requestAll ( std::span< const std::string > keys )

request() every key; stops at the first hard failure.

参数

keys	Borrowed list of cache keys; duplicates share one in-flight job.

在文件 Resource.cpp 第 207 行定义.

引用了 eve::Applied, key, request, eve::Status::success() , 以及 eve::Result< T >::success().

◆ runLoadJob()

void eve::ResourceManager::runLoadJob	(	std::string	norm,
		uint64_t	epoch
	)

protected

Run load job.

在文件 Resource.cpp 第 75 行定义.

引用了 cv_, epoch, epoch_, error, loadUncached(), mu_, pending_, registry_ , 以及 resources.

被这些函数引用 request().

◆ unload()

void eve::ResourceManager::unload ( std::string key )

Drop the exact cache entry key (parameters included). The resource stays alive while other holders still reference it.

在文件 Resource.cpp 第 332 行定义.

引用了 key, makeKey(), mu_, registry_ , 以及 resources.

◆ unloadPath()

void eve::ResourceManager::unloadPath ( const std::string & path )

Drop every cache entry whose path matches, whatever its parameters.

在文件 Resource.cpp 第 343 行定义.

引用了 mu_, normalizePath(), path, pathOfKey(), registry_ , 以及 resources.

◆ waitFor()

ResultRef< Resource > eve::ResourceManager::waitFor ( std::string key )

Block until key is cached, failed, or unclaimed.

参数

key	Cache key; starts a load if neither cached nor in flight.

返回: Borrowed resource on success; NotFound / Failed otherwise. @ownership Borrowed from the cache on success. @lifetime Same as get(). @thread Game thread; waits for a worker if request() is in flight. @reentrancy Must not be called from a worker that this wait would join on the same pool (deadlock).

在文件 Resource.cpp 第 226 行定义.

引用了 borrowLocked(), cv_, ensureRegistered(), eve::Diagnostic::error(), eve::Failed, eve::Result< T >::failure(), eve::InvalidArgument, key, loadUncached(), makeKey(), mu_, eve::NotFound, pending_, registry_, resources , 以及 eve::Result< T >::success().

被这些函数引用 get(), eve::graphics::vulkan::Graphics::newTextureFromFile(), eve::graphics::webgpu::Graphics::newTextureFromFile() , 以及 eve::filesystem::readPreparedFile().

类成员变量说明

◆ cv_

std::condition_variable eve::ResourceManager::cv_

protected

在文件 Resource.h 第 338 行定义.

被这些函数引用 clear(), request(), runLoadJob() , 以及 waitFor().

◆ epoch_

uint64_t eve::ResourceManager::epoch_ = 1

protected

在文件 Resource.h 第 339 行定义.

被这些函数引用 clear(), request() , 以及 runLoadJob().

◆ mu_

std::mutex eve::ResourceManager::mu_

mutableprotected

在文件 Resource.h 第 337 行定义.

被这些函数引用 clear(), count(), ensureRegistered(), handlesPath(), peek(), pendingCount(), pin(), reload(), request(), runLoadJob(), unload(), unloadPath() , 以及 waitFor().

◆ pending_

std::unordered_map<std::string, std::shared_ptr<AsyncLoad> > eve::ResourceManager::pending_

protected

在文件 Resource.h 第 336 行定义.

被这些函数引用 clear(), pendingCount(), request(), runLoadJob() , 以及 waitFor().

◆ registered_

bool eve::ResourceManager::registered_ = false

protected

在文件 Resource.h 第 340 行定义.

被这些函数引用 clear() , 以及 ensureRegistered().

◆ registry_

script::RuntimeObjectRegistry<Resource, ResourceCacheTag> eve::ResourceManager::registry_

protected

Registry that exclusively owns every cached resource.

在文件 Resource.h 第 334 行定义.

被这些函数引用 clear(), pin(), reload(), runLoadJob(), unload(), unloadPath() , 以及 waitFor().

◆ resources

std::map<std::string, ResourceRef> eve::ResourceManager::resources

protected

在文件 Resource.h 第 335 行定义.

被这些函数引用 clear(), count(), handlesPath(), peek(), pin(), reload(), request(), runLoadJob(), unload(), unloadPath() , 以及 waitFor().

该类的文档由以下文件生成:

src/engine/common/Resource.h
src/engine/common/Resource.cpp

类

Public 成员函数

静态 Public 成员函数

Protected 类型

Protected 成员函数

Protected 属性

额外继承的成员函数

详细描述

成员类型定义说明

◆ ResourceRef

构造及析构函数说明

◆ ResourceManager()

成员函数说明

◆ borrowLocked()

◆ clear()

◆ count()

◆ ensureRegistered()

◆ get()

◆ getInstance()

◆ handlesPath()

◆ load()

◆ loadReplacement()

◆ loadUncached()

◆ makeKey()

◆ normalizePath()

◆ pathOfKey()

◆ peek()

◆ pendingCount()

◆ pin()

◆ reload()

◆ reloadKind()

◆ request()

◆ requestAll()

◆ runLoadJob()

◆ unload()

◆ unloadPath()

◆ waitFor()

类成员变量说明

◆ cv_

◆ epoch_

◆ mu_

◆ pending_

◆ registered_

◆ registry_

◆ resources