Module crayon::resource

The standardized interface to load data asynchronously from the Filesystem, and provides utilities for modules to implement their own local resource management.

This is a very general overview of the resource management philosophy in Crayon. Modules are completely free to implement their own resource management and don’t need to adhere to this basic philosophy.

For specific information on how to create and use resources, please read the particular module documentations.

Resource Management

A resource is a very slim proxy object that adds a standardized interface for creation, destruction, sharing and lifetime management to some external object or generally ‘piece of data'.

Its recommanded to use a unique Handle object to represent a resource object safely. This approach has several advantages, since it helps for saving state externally. E.G.:

1. It allows for the resource to be destroyed without leaving dangling pointers.
2. Its perfectly safe to store and share the Handle even the underlying resource is loading on the background thread.

In some systems, actual resource objects are private and opaque, application will usually not have direct access to a resource object in form of reference.

Sharing

Safe resource sharing is implemented through resource's Location. A Location object has ( in its usual form) a Path slice that serves as a human-readable identifier, and (for resources that are loaded from a filesystem) also as an URL.

And besides the Path part, there is a additional Signature field in Location. A Signature is usually a integer which is used to restrict sharing. Two Locations are only identical if both the path and signature match. This can be used to suppress resource sharing even if the path (e.g. the filename) of two Locations matches.

let l1 = Location::shared(0, "/path/to/res");
let l2 = Location::shared(0, "/path/to/res");
assert!(l1 == l2);

let l3 = Location::shared(1, "/path/to/res");
assert!(l1 != l3);

There is one special Unique signature which disables sharing of a resource completely, and always makes the resource object unique, no matter how many other shared or non-shared resources with the same name exist, this is most useful to enforce private ownership of a resource without having to care about name collisions.

let l1 = Location::shared(0, "/path/to/res");
let l2 = Location::shared(0, "/path/to/res");
assert!(l1 == l2);

let l3 = Location::unique("/path/to/res");
let l4 = Location::unique("/path/to/res");
assert!(l1 != l3);
assert!(l3 != l4);

Lifetime (TODO)

Asynchronization (TODO)

Modules

cache
errors
filesystem	The virtual file-system module that allows user to load data asynchronously.

Structs

Location	A Location describes where the source data for a resource is located. It usually contains a Path that can be resolved to an URI. Locations are also used for sharing. If 2 Locations are completely identical, they identify the same resource.
Registery	Compact resource registery.
ResourceSystem	Takes care of loading data asynchronously through pluggable filesystems.
ResourceSystemShared	The multi-thread friendly parts of ResourceSystem.

Traits

ResourceAsyncLoader

The callbacks of async loader.