5 Environment

5.1 The state and memory

(1) A processor runs only inside the one block of bytes the host gave it. After a state is opened, the processor asks the operating system for no memory. When the block is too small, the operation fails with PINAX_ERR_NO_ROOM; nothing is written outside the block.

(2) Every value of a state is in one of these places: a declared global (clause 8), a slot of the stack or of a local (clause 9), the region of a task (12.2), or memory the host gave and vouches for (bound and shared storage, 8.12, 8.13; strings passed in; KEEP_STR results, 19.3). There is no other place. A value refers to another value by number (the number of a row, a handle).

(3) A state uses no global or thread-local variables. Two states can therefore run at the same time on two threads. One state is used by one thread at a time.

5.2 Loading

(4) A state takes any number of sources, one after the other. To load a source, the processor:

1. splits the source into tokens (clause 6) and reads its syntax;
2. reads it once from top to bottom, checking names, types, the depth of the stack, the handling of failures and the handing over of owned values;
3. when all is kept, runs once, in the order written, the code written outside definitions.

(5) The code outside definitions (load code) can use the words and globals of its source. The code inside a word definition runs when the word is called.

use io
"first: code outside definitions runs once, at load" io.println
word greet (gives s str) "second: a word runs when it is called" end
greet io.println

$ pnx 05-load-order.pnx
first: code outside definitions runs once, at load
second: a word runs when it is called

(6) When (4) 1 or 2 refuses, 3 does not happen. Not even load code written early in the source runs.

use io
"this line is never printed" io.println
word broken (n int gives r int) n "one" add end

$ pnx 05-refused-runs-nothing.pnx
05-refused-runs-nothing.pnx:3:41: this word takes two int values, or two of the same declared type

(7) When load code stops with a fault, the load fails, and the words and globals that source added are gone. Values that code stored into globals of sources loaded before, and what host words have already done, are not undone.

(8) There are two kinds of load. A code load accepts everything this document defines. A data
load accepts declarations and values only and refuses word definitions, calls and control (13.4). It is for text that is not trusted, such as settings files.

5.3 Running

(9) The host finds a word by name and signature (clause 19), runs it with arguments and receives its results. A run has a budget of instructions. When it is used up the run remembers where it stopped and returns to the host; when the host continues it, it goes on from there. The budget does not change results.

(10) Below is a whole host program. It registers one word, loads a source and calls a word of the script.

#include "pinax.h"
#include <stdio.h>

/* A host word: the script calls it as calc.tenfold. */
static pinax_err tenfold(pinax_call *call, void *user, const pinax_args *args) {
    (void)call; (void)user;
    if (args->i[0] > INT64_MAX / 10 || args->i[0] < INT64_MIN / 10)
        return PINAX_ERR_OVERFLOW;              /* as the script's own mul would: a fault */
    args->ri[0] = args->i[0] * 10;
    return PINAX_OK;
}

int main(void) {
    static unsigned char block[1 << 20];          /* the whole state lives in here */
    pinax_config config = {.struct_size = sizeof config, .budget = 100000};
    pinax_state *st;
    if (pinax_open((pinax_mem){block, sizeof block}, &config, &st) != PINAX_OK)
        return 1;

    static const pinax_word_def words[] = {{"tenfold", "(n int gives r int)", tenfold, NULL, 0}};
    pinax_register(st, "calc", words, 1);

    static const char source[] =
        "use calc\n"
        "word answer (n int gives r int) n calc.tenfold 2 add end\n";
    pinax_str text = {(const unsigned char *)source, sizeof source - 1};
    if (pinax_load(st, "main", text, PINAX_LOAD_CODE) != PINAX_OK) {
        pinax_str why = pinax_error_text(st);
        fprintf(stderr, "%.*s\n", (int)why.len, (const char *)why.ptr);
        return 1;
    }

    pinax_word answer;
    pinax_find(st, "answer", "(n int gives r int)", 0, &answer);
    int64_t in = 4, out = 0;
    pinax_args args = {.i = &in, .ri = &out};
    pinax_err err = pinax_run(st, answer, &args);
    while (err == PINAX_SUSPENDED)                 /* the instruction budget ran out */
        err = pinax_resume(st, &args);
    printf("answer(4) = %lld\n", (long long)out);
    pinax_close(st);
    return 0;
}

$ ./05-embed
answer(4) = 42

(11) The command pnx is one host using this library. It loads a file, runs its load code and registers the standard host modules (clause 17). Most examples in this document are run with pnx (clause 20).