`tecs.assets`

Acquires assets without blocking the host, and owns what a caller holds.

A load returns the asset. There is no future, no promise and no callback in the game-facing signature: a request that cannot answer at once parks its coroutine through nupp.suspension and resumes with the answer, so the same call reads the same way inside a frame system and inside a startup script.

local loader = app.assets
local handle, reason = loader:request(tecs.assets.bytes, "levels/one.json")
if handle == nil then
    return nil, reason
end
local text <const> = handle:value() as string
handle:release()

Application creates app.assets and shuts it down after world shutdown. Standalone tools may use newAssets and must call shutdown themselves. Settled handles remain valid until their owners release them; stopping the loader cancels acquisitions, not those existing holds.

Inside a system the same two lines suspend the logical update rather than the thread, and the host renders the frames that pass while the file is read. Where no suspension handler is installed, the built-in driver runs the readiness pumps on this thread and the call still returns the asset.

What this module owns, and what it does not#

This is orchestration: requesting, sharing an acquisition between callers that want the same thing, counting holds, replacing a payload in place and reporting a failure to the call that asked for it. Reading bytes, decoding pixels, uploading a texture and freeing a native allocation belong to a Kind, which supplies a Job per acquisition and a release for the payload it produced. A GPU service registers a kind whose job issues its own upload command; nothing about textures is written here.

Failure#

An invalid argument raises at the call: an empty path, a released handle, a loader that has shut down. A load that could not produce its asset answers nil, reason from request, whether it failed before parking or hours later. The readiness pump never raises a load failure of its own, because the call that asked for the asset is the only place the reason means anything; the pump resumes that call and lets it return the pair its signature promises.

Holds and residency#

A Handle is a hold, not a cache entry. Two requests for one path that overlap share one acquisition and receive holds on one handle, because decoding the same file twice at once duplicates work without producing another result. A request made after the first settles acquires again: nothing here retains a settled asset behind the caller's back, and the payload lives exactly as long as the holds on it.

release gives up one hold, and the last one frees the payload through the kind. Releasing a handle already down to nothing does nothing, so a shutdown path need not know whether something else got there first.

Replacement#

reload acquires the same path again and swaps the result into a handle every holder already has, then frees what it displaced. The handle's identity does not change and its revision advances, which is what a consumer holding device state keyed on the handle watches to know its copy is stale. A failed reload leaves the resident payload exactly as it was and answers false, reason.

Module contents

Constructors

Constructor	Description
`newAssets`	Creates a loader with nothing in flight and its readiness pump registered.

Types

Type	Kind	Description
`Assets`	record	A loader: the acquisitions in flight, the holds they produced, and the readiness pump that advances them.
`Handle`	record	A caller's hold on one acquired asset.
`Job`	record	One acquisition in progress, owned by the kind that opened it.
`Kind`	record	How one class of asset is acquired and freed.
`Status`	type	Where one acquisition stands.

Functions

Function	Kind	Description
`readJob`	function	Begins a complete file read that settles on the readiness pump.

Values

Value	Kind	Description
`bytes`	variable	Reads a complete file into a binary-safe string without interpreting it.
`DOCUMENT`	variable	Read-only.
`FONT`	variable	Read-only.
`IMAGE`	variable	Read-only.
`MODEL`	variable	Read-only.
`SHADER`	variable	Read-only.
`SOUND`	variable	Read-only.

Constructors#

`newAssets`constructor#

function newAssets(): Assets

Creates a loader with nothing in flight and its readiness pump registered.

The pump reports itself inactive while nothing is in flight, so a program with no suspension handler never sleeps on a loader that has no work.

Returns

Type	Description
`Assets`	the running loader

Types#

`Assets`record#

record Assets

    request: function(self: Assets, kind: Kind, path: string): (Handle?, string?)
    reload: function(self: Assets, kind: Kind, handle: Handle): (boolean, string?)
    drain: function(exclusive self: Assets): (boolean, string?)
    pending: function(borrows self: Assets): integer
    resident: function(borrows self: Assets): integer
    running: function(borrows self: Assets): boolean
    shutdown: function(exclusive self: Assets): nil
end

A loader: the acquisitions in flight, the holds they produced, and the readiness pump that advances them.

One loader per application. Two loaders share nothing, which is what makes a test able to shut one down without disturbing anything else in the process.

Methods

`request`#

request: function(self: Assets, kind: Kind, path: string): (Handle?, string?)

Requests one asset and returns the caller's hold on it.

The call suspends only while the acquisition is pending. Two overlapping requests for one kind and path share the acquisition and receive holds on one handle; a request made after the first settles acquires again.

The receiver is plain rather than exclusive, because the entry this registers names the loader it belongs to and outlives the call.

Arguments

Name	Type	Description
`self`	`Assets`
`kind`	`Kind`
`path`	`string`

Returns

Type	Description
`Handle?`
`string?`

Raises

when the path is empty or the loader has shut down

`reload`#

reload: function(self: Assets, kind: Kind, handle: Handle): (boolean, string?)

Acquires an asset again and replaces what a handle already holds.

Every holder sees the new payload through the handle it already has, and the handle's revision advances so a consumer keyed on it can tell its own copy is stale. The displaced payload is freed through the kind once the swap has happened. A failed acquisition changes nothing and reports why.

The receiver is plain rather than exclusive, because the replacement entry names the loader it belongs to and outlives the call.

Arguments

Name	Type	Description
`self`	`Assets`
`kind`	`Kind`
`handle`	`Handle`

Returns

Type	Description
`boolean`
`string?`

Raises

when the loader has shut down, the handle is released, or the handle belongs to another loader or another kind

`drain`#

drain: function(exclusive self: Assets): (boolean, string?)

Suspends until nothing is in flight.

This is the startup and shutdown barrier, and it waits on every acquisition this loader owns rather than only the caller's. It returns at once when nothing is pending.

Arguments

Name	Type	Description
`exclusive self`	`Assets`

Returns

Type	Description
`boolean`
`string?`

Raises

when the loader has already shut down

`pending`#

pending: function(borrows self: Assets): integer

Returns the number of acquisitions still in flight.

Arguments

Name	Type	Description
`borrows self`	`Assets`

Returns

Type	Description
`integer`

`resident`#

resident: function(borrows self: Assets): integer

Returns the number of handles still holding a payload.

Arguments

Name	Type	Description
`borrows self`	`Assets`

Returns

Type	Description
`integer`

`running`#

running: function(borrows self: Assets): boolean

Reports whether this loader still accepts requests.

Arguments

Name	Type	Description
`borrows self`	`Assets`

Returns

Type	Description
`boolean`

`shutdown`#

shutdown: function(exclusive self: Assets): nil

Stops the loader and reports the stop to every parked caller.

Every acquisition in flight is cancelled and every parked request resumes and returns nil, reason from the call that asked for the asset, rather than raising somewhere the reason means nothing. Handles that already settled keep their payloads and still release correctly, so this frees nothing a caller still holds.

Calling it twice does nothing the second time.

Arguments

Name	Type	Description
`exclusive self`	`Assets`

Returns

Type	Description
`nil`

`Handle`record#

record Handle
    path: string
    kind: string

    value: function(borrows self: Handle): any?
    resident: function(borrows self: Handle): boolean
    revision: function(borrows self: Handle): integer
    holds: function(borrows self: Handle): integer
    retain: function(exclusive self: Handle): nil
    release: function(exclusive self: Handle): nil
end

A caller's hold on one acquired asset.

Handles are shared: every caller whose request joined one acquisition gets this same object, and the payload lives until the last of them releases it.

Methods

`value`#

value: function(borrows self: Handle): any?

Returns the payload this handle holds.

The kind that acquired it decides what this is, so the caller casts once: handle:value() as Image. Nothing below checks that cast.

Arguments

Name	Type	Description
`borrows self`	`Handle`

Returns

Type	Description
`any?`

`resident`#

resident: function(borrows self: Handle): boolean

Reports whether the payload is still in memory.

Arguments

Name	Type	Description
`borrows self`	`Handle`

Returns

Type	Description
`boolean`

`revision`#

revision: function(borrows self: Handle): integer

Returns how many times this handle's payload has been replaced.

A consumer that keeps device state derived from the payload stores the revision beside it and re-derives when the two differ.

Arguments

Name	Type	Description
`borrows self`	`Handle`

Returns

Type	Description
`integer`

`holds`#

holds: function(borrows self: Handle): integer

Returns the number of callers holding this payload.

Arguments

Name	Type	Description
`borrows self`	`Handle`

Returns

Type	Description
`integer`

`retain`#

retain: function(exclusive self: Handle): nil

Takes one more hold on this payload.

Call it when passing a handle somewhere with a lifetime of its own, so the two owners release independently.

Arguments

Name	Type	Description
`exclusive self`	`Handle`

Returns

Type	Description
`nil`

Raises

when the payload has already been freed

`release`#

release: function(exclusive self: Handle): nil

Gives up this caller's hold, and frees the payload at the last one.

Call it once whatever needed the asset has taken ownership. Releasing a handle already down to nothing does nothing, so a shutdown path need not know whether something else got there first.

Arguments

Name	Type	Description
`exclusive self`	`Handle`

Returns

Type	Description
`nil`

Fields

`path`#

path: string

Read-only. Contains the requested path unchanged. The loader does not resolve it, so it is whatever the caller passed.

`kind`#

kind: string

Read-only. Contains the content kind name this asset was acquired under.

`Job`record#

record Job
    poll: function(): (Status, any?, string?)
    cancel: function(): nil
end

One acquisition in progress, owned by the kind that opened it.

A job is driven by the loader's readiness pump, never by the caller. It runs on whatever the kind uses underneath: a file read, a worker channel, a native service reply. Nothing here assumes which.

Methods

`poll`#

poll: function(): (Status, any?, string?)

Advances the acquisition and reports where it stands.

Answers "pending" alone while the work continues, "ready" and the payload once it is done, or "failed" and a non-empty reason. The loader stops calling it after the first answer that is not "pending", and the payload it hands back becomes the loader's to free through the kind.

Returns

Type	Description
`Status`
`any?`
`string?`

`cancel`#

cancel: function(): nil

Abandons the acquisition and frees anything it holds.

The loader calls it at most once, and only for a job that has not answered "ready" or "failed". It must not raise.

Returns

Type	Description
`nil`

`Kind`record#

record Kind
    name: string
    open: function(path: string): (Job?, string?)
    release: (function(value: any): nil)?
end

How one class of asset is acquired and freed.

A payload is whatever the kind's job produced, so this layer types it as any and the caller casts once at value. A phantom type parameter would move that cast rather than check it, and the loader would still be handing back what the job supplied.

Methods

`open`#

open: function(path: string): (Job?, string?)

Read-only. Begins one acquisition of path.

Answers the job that will produce the payload, or nil, reason where the acquisition cannot start at all. A refusal here reaches the requesting call without parking it.

Arguments

Name	Type	Description
`path`	`string`

Returns

Type	Description
`Job?`
`string?`

Fields

`name`#

name: string

Read-only. Contains the content kind name this asset is recorded under, which is the string file watching and tooling filter on.

`release`#

release: (function(value: any): nil)?

Read-only. Frees one payload after its last hold goes. Nil where the collector owns the payload outright, which is true of a plain Lua string.

`Status`type#

type Status = "pending" | "ready" | "failed"

Where one acquisition stands.

Functions#

`readJob`function#

function readJob(path: string): Job?, string?

Begins a complete file read that settles on the readiness pump.

The read itself runs in the pump's pass rather than in the requesting call, so a request for a file parks and resumes exactly as one for a decoded asset does. A kind that needs the bytes before it can do its own work composes this job rather than reading the file inline.

Arguments

Name	Type	Description
`path`	`string`	the file to read

Returns

Type	Description
`Job?`	the job that answers the complete bytes
`string?`	a failure reason, when the read cannot be started

Values#

`bytes`variable#

const bytes: Kind

Reads a complete file into a binary-safe string without interpreting it.

A handle of this kind carries a string, so handle:value() as string is the cast its caller writes. The collector owns the string and the kind frees nothing. Releasing the handle still matters: it is what tells the loader the asset is no longer resident.

`DOCUMENT`variable#

const DOCUMENT

Read-only. Names the content kind of a file loaded without interpretation.

`FONT`variable#

const FONT

Read-only. Names the content kind of a loaded font.

`IMAGE`variable#

const IMAGE

Read-only. Names the content kind of a decoded image.

`MODEL`variable#

const MODEL

Read-only. Names the content kind of a decoded model scene.

`SHADER`variable#

const SHADER

Read-only. Names the content kind of a loaded shader.

`SOUND`variable#

const SOUND

Read-only. Names the content kind of a loaded sound.

tecs.assets

What this module owns, and what it does not#

Failure#

Holds and residency#

Replacement#

Module contents

Constructors

Types

Functions

Values

Constructors#

newAssetsconstructor#

Returns

Types#

Assetsrecord#

Methods

request#

Arguments

Returns

Raises

reload#

Arguments

Returns

Raises

drain#

Arguments

Returns

Raises

pending#

Arguments

Returns

resident#

Arguments

Returns

running#

Arguments

Returns

shutdown#

Arguments

Returns

Handlerecord#

Methods

value#

Arguments

Returns

resident#

Arguments

Returns

revision#

Arguments

Returns

holds#

Arguments

Returns

retain#

Arguments

Returns

Raises

release#

Arguments

Returns

Fields

path#

kind#

Jobrecord#

Methods

poll#

Returns

cancel#

Returns

Kindrecord#

Methods

open#

Arguments

Returns

Fields

name#

release#

Statustype#

Functions#

`tecs.assets`

`newAssets`constructor#

`Assets`record#

`request`#

`reload`#

`drain`#

`pending`#

`resident`#

`running`#

`shutdown`#

`Handle`record#

`value`#

`resident`#

`revision`#

`holds`#

`retain`#

`release`#

`path`#

`kind`#

`Job`record#

`poll`#

`cancel`#

`Kind`record#

`open`#

`name`#

`release`#

`Status`type#

`readJob`function#

`bytes`variable#

`DOCUMENT`variable#

`FONT`variable#

`IMAGE`variable#

`MODEL`variable#

`SHADER`variable#

`SOUND`variable#