Ares

From EPD Wiki
Revision as of 11:31, 12 April 2024 by Watertoon (talk | contribs) (Draft an outline of the library)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Ares is Nintendo's Asynchronous Resource library. Meant for managing resources, primarily files and their memory asynchronously.

Backend

System

Manages 3 thread types, a Control thread, a Memory thread, and a set of Load threads. Control primarily handles ResourceUnit management related tasks. Memory mainly handles memory management related tasks. While Load threads mainly handle file load operations. The System also maintains structures such as a list of ResourceSizeTables, MemoryMgrs, sets of decompressors, a ResourceUnit request queue, OnThreadUnitPools for allocating LoadOnThreadUnit and ClearCacheOnThreadUnits, as well as callbacks for OnThreadUnits and OnThreadUnits for internal use.

IApplicationSystem

Implemented by application. Provides callbacks to get the supported file extensions and which of those extensions use which of the 3 supported compression formats, a method to format the system thread initialize arguments, a method to look up a MemoryMgr based on resource size and path, and more.

MemoryMgr

Initialized by application. Manages memory and heap creation for resource units. The MemoryMgr's root heap can be a sead::ExpHeap, sead::VirtualAddressHeap, or a user provided heap type.

ThreadLocalArchiveMgr

Manages the thread local storage for the user set thread local archive resource via a pool of thread references.

ResourceSizeTable

Manages an rsizetable. Allows looking up a resource's size by a file path.

ResourceMgr

Manages a tree of resource units. Allows the System to iterate ResourceUnits under a file extension, and attempt to reference existing ResourceUnits during a load operation.

ResourceUnitPool

Allocator for ResourceUnits.

ResourceUnit

Resource meta data, such as the file path the resource came from, the Status, the FileDevice, the ResourceFactory, the MemoryMgr, the Resource itself, the ResourceMgr, as well as an Event and OnThreadUnit for background operations.

thread::ExeQueue

A queue for scheduling OnThreadUnits through a set of ExeQueueThreads with respect to their priority, amount of priority levels and ExeQueueThreads adjustable.

thread::CSExeQueue

A thread safe derivative of ExeQueue via CriticalSection, only addition, only ExeQueue class observed used.

thread::ExeQueueThread

A thread that processes OnThreadUnits asynchronously.

thread::OnThreadUnit

An encapsulation of a unit of work to be processed by an ExeQueue. Has 2 user provided callbacks at time of scheduling, Execute and Result, result can reschedule the current OnThreadUnit. Virtual callbacks are provided for derived OnThreadUnit types.

thread::OnThreadUnitPool

A pool of OnThreadUnits, allows the user to create pools of derived ForPoolOnThreadUnit classes.

thread::ForPoolOnThreadUnit

Extends OnThreadUnit with integration related to OnThreadUnitPool.

thread::OnThreadUnitWatcher

Allows a user to watch a ForPoolOnThreadUnit for completion.

LoadOnThreadUnit

Extends ForPoolOnThreadUnit with additional meta data and management related to loading files. Used to queue asynchronous load operations.

ClearCacheOnThreadUnit

Controllers

ResourceBinder

Used to bind a resource. Stores a ResourceUnit reference and an OnThreadUnitWatcher. Supports loading a file asynchronously or synchronously, waiting for the load to complete, initializing the resource, acquiring the resource, and releasing the resource. Making requests from multiple threads on a single resource binder is not thread-safe, however it is thread-safe to attempt any operation even during resource loading.

Thread Local Archive Api

A scoped thread local archive setter is provided, as well as a direct function for setting the current local archive. A ResourceBinder binding an archive resource must be provided, else the current local archive will be unset.

Threading Api

An interface is provided to suspend, to resume, and to adjust the priority or core masks of the 3 thread types.