Content: named records

Named records are small pieces of data a program keeps on the host it runs on: a high score, settings, a saved game, a shell's layout. Four operations of the content device (device 4) save, load, delete and list them. They use the same request block, submit call (400h), handles, completion rules and statuses as get and put, described in "Content: blobs, requests and statuses", which comes before this article. Records never leave the host: they are not sent to a relay, to another host or to another program.

opOperationC helper
0EhSaverecord_save(r, name, data, size)
0FhLoadrecord_load(r, name, offset, length, buf)
10hDeleterecord_delete(r, name)
11hRecordsrecord_list(r, first, length, buf)

Names

For save, load and delete, the block's id field (32 bytes at offset 4) holds the record's name: 1 to 32 bytes of UTF-8 with no control characters (U+0000 to U+001F, U+007F to U+009F), then 00h to the end of the 32 bytes. Any other id (empty, not UTF-8, a control character, a non-zero byte after the first 00h) makes the request a bad request: the submit returns 0 and writes status 04h. For records (11h) id is not used.

The C helpers take a zero-terminated string and copy at most 32 bytes of it, padding with zeros; a longer string is cut at 32 bytes without warning, which can also cut a UTF-8 character in half (then the submit fails with 04h).

Owner

The records a machine reaches belong to an owner, and a program cannot reach another owner's records.

How the machine was startedOwner
by a shell with start_programthe program's identity, (feed key, name); for a built-in, the all-zero key and its title. Every version shares the records
by the host, as its built-in shellthe shell's identity, as above
with start by image ID, or from a filethe exact image ID: a rebuilt image has new, empty records

So publishing a new version of a program under the same name keeps its records, while a program run from a file during development has records of its own. Moving records from one owner to another (for example when a program run from a file is later published) is not specified yet.

Operations

OperationFieldsCompletion
Save 0Ehaddr and size: the data, 0 to 65,536 bytes, wholly in ROM or wholly in RAM, copied at submit01h once the record is replaced and durably stored; 06h if it would exceed the limits, and nothing changes
Load 0Fhoffset; length 1 to 16,384; addr, length bytes in RAMas a get: the bytes from offset to addr, length = bytes delivered, size = the record's size; 02h if there is no such record
Delete 10hnone besides id01h, whether or not the record existed
Records 11hoffset (first index), length 1 to 16,384, addr in RAMrecords of 36 bytes, in increasing order of name (byte order); length = bytes delivered, size = number of records

A save of 0 bytes is allowed and makes an empty record. A save always replaces the whole record; there is no append. A load whose offset is at or beyond the end of the record completes with 01h, length 0 and size the record's size.

Each record of the records list:

OffsetSizeField
032the name, padded with 00h
324the record's size in bytes

"Durably stored" means the host wrote the data to a temporary file, synced it, and renamed it into place, so a record is replaced as a whole or not at all.

Limits

LimitValue
name1 to 32 bytes
one record0 to 65,536 bytes
records per owner256
data per owner1,048,576 bytes in all
bytes per load or list request16,384

A save that would exceed either per-owner limit, counting the record it replaces as gone, completes with 06h (STATUS_NO_ROOM) and changes nothing. A record larger than 16,384 bytes is loaded in several requests with increasing offset.

Statuses

StatusWhen
01hdone
02hload: no such record
03hthe host cannot keep records (no data directory, an I/O error); also any request pending when the machine was restored from a snapshot
04hat submit: a bad name, a size or length out of range, a buffer not where required
06hsave: over the owner's limits

No consent is asked for any of the four. A host that offers only the machine's reading profile may complete all four with 05h without carrying them out; a program should treat that as "not on this host".

Charges

Each submit costs 4 units. An accepted save also costs 1 unit per 4 bytes of its data (rounded up), at submit. The bytes a load or a records list writes to addr cost 1 unit per 4 bytes, rounded up, taken from the budget of the frame they arrive in. See charges; completions are announced by a content-done event, see events.

Replay

Record requests are inputs like every completion: what a load delivers and the status of a save are recorded with the run, so a run replays exactly without the records directory. The records themselves are not part of the machine's state; only the pending requests are.

Where hosts keep them

Hosts keep records under <data>/records, where <data> is the --data option of terse run and terse-host, by default $XDG_DATA_HOME/terse, else ~/.local/share/terse. Inside, each owner has a directory, program/<feed key hex>/<name hex>/ (built-ins have the all-zero key) or image/<image ID hex>/, and each record is a file named by the hex of its name. The terse tool inspects them:

CommandEffect
terse records list [<owner>] [--data <dir>]every owner with its count and bytes, or one owner's records (size, name)
terse records show <owner> <name>writes the record's bytes to standard output
terse records delete <owner> <name>deletes the record

An owner is written builtin:<title>, program:<feed key>:<name> or image:<image id>.

Example: a high score

This is how the game Sparks (programs/sparks) keeps its high score in a 4-byte record named high-score. The load is asked for at start and handled when it arrives, so the first frame does not wait; a save is sent at game over and its completion is ignored.

#include "terse.h"

static content_req load_req, save_req;
static uint8_t buf[4], load_handle;
static uint32_t high;

void start(void)
{
    load_handle = record_load(&load_req, "high-score",
                              0, 4, buf);
}

/* For each event in the main loop. */
void on_event(const terse_event *ev)
{
    if (ev->type != EV_CONTENT_DONE || ev->a != load_handle)
        return;
    load_handle = 0;
    if (load_req.status == STATUS_DONE
        && load_req.length == 4) {
        uint32_t v = buf[0] | buf[1] << 8 | buf[2] << 16
                   | (uint32_t)buf[3] << 24;
        if (v > high) /* a score made meanwhile wins */
            high = v;
    }
}

void game_over(uint32_t score)
{
    if (score <= high)
        return;
    high = score;
    for (int i = 0; i < 4; i++)
        buf[i] = (uint8_t)(high >> (8 * i));
    record_save(&save_req, "high-score", buf, 4);
}

The save copies its 4 bytes at submit, so buf may change at once. The first time the game runs there is no record and the load completes with 02h; high stays 0. Use separate request blocks for requests that may be pending at the same time, as here: submitting a block again while it is pending makes two requests that both write their results into it.