Files
LithosAnanke/v4/include/v4/fabric.h
T
Claude edbb79e2af v4 fabric: each pass of a step walks only the places that hold a node (mechanism A)
The fabric keeps its occupied places as a list in ascending order, and
the step's nine passes walk that list in the same order as before. A
place removed mid-walk keeps its link, so the walk goes on to the next
node.

Test first: test_fabric_walk.c, 13 checks.

Every existing fabric and mesh test passes with the same checks, and so
do test-32 and ASan/UBSan. The host mesh boot runs POST 990/990. Over
five alternating runs its median falls from 11.695 s to 7.999 s.

Logs are in logs/20261117-mechanism-a.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-17 22:23:58 +00:00

193 lines
10 KiB
C

/* SPDX-License-Identifier: LicenseRef-Starship-1.0
* Copyright (c) 2023-2026 Robert A. James
*/
/* fabric.h -- the nodes there are, how their ports are wired, and time
* passing for all of them at once. docs/v4.0.0/MESH.md 4.3.
*
* On the fabric every node runs at the same time and a node with nothing to
* do is blocked at a port. Here that is: every node that is awake and not
* blocked executes one instruction word; then every operation on a whole
* message that a node asked for is done (WHOLE MESSAGES, below); and then
* every word written that has a reader waiting on the other end of its wire
* is handed over. There is no choice of whose turn it is.
*
* THE GEOMETRY IS DATA. Which port connects to what is a table, and it can
* be changed while the nodes run; nodes can be added and removed while they
* run. Nothing here knows what shape the wiring makes.
*
* Nothing here knows what the nodes are for, either: no message, no
* capsule, no StarForth. And nothing here uses the C library: whoever owns
* the fabric supplies the memory for it and for each node.
*/
#ifndef V4_FABRIC_H
#define V4_FABRIC_H
#include "v4/exec.h"
#include "v4/wire.h"
/* What is on the other end of a port that is not a node: a console, a disk,
* the kernel that serves a node's requests. Either function may be 0. */
typedef struct {
int (*take)(void *self, v4_cell value); /* the node wrote `value`: 1 if it is taken, 0 if not yet */
int (*give)(void *self, v4_cell *value); /* the node is reading: 1 with a word in *value, 0 if not yet */
void *self;
} v4_device;
/* One end of a wire. */
enum { V4_WIRE_NONE = 0, V4_WIRE_NODE, V4_WIRE_DEVICE };
typedef struct {
int kind;
unsigned node, port; /* V4_WIRE_NODE: the other node and its port */
const v4_device *device; /* V4_WIRE_DEVICE */
v4_wire_queue *rx, *tx; /* the messages that come to this end of the wire, and that go from it (7d.2); 0: none */
} v4_wire;
/* A node, with what the engine needs to run it. Its owner supplies one of
* these for every node there is to be. */
typedef struct {
v4_node n;
v4_exec_state es;
v4_heat h;
} v4_fabric_node;
/* A place in the fabric: a node, or nothing. */
typedef struct {
v4_fabric_node *node; /* 0: no node here */
int asleep;
int cut; /* not 0: a wire of this node's has been cut since it was last woken by that (operation 9) */
v4_wire wire[V4_PORTS];
unsigned next; /* the walk (mechanism A): the next place that holds a node, plus one; 0: none. The fabric's own. */
} v4_place;
typedef struct {
v4_place *place;
unsigned capacity;
v4_wire_queue *queue; /* see v4_fabric_queues; 0: none were given */
unsigned queue_count, queue_free; /* how many, and how many are not on a wire */
unsigned queue_first; /* the first that is not, and the index plus one; 0: none. Each links to the next by its `head`. */
v4_cell gone_error; /* see v4_fabric_gone_error; 0: none */
unsigned first; /* the walk: the first place that holds a node, plus one; 0: none */
} v4_fabric;
/* An empty fabric with room for `capacity` nodes, in `places`. */
void v4_fabric_init(v4_fabric *f, v4_place *places, unsigned capacity);
/* THE WIRES' MEMORY (MESH.md 7d.2). Between two nodes that are wired, or a
* node and a device, the fabric keeps two queues of whole messages, one each
* way (wire.h). The owner gives it the queues: `count` of them, in `pool`,
* before anything is wired. Wiring a port takes two, cutting it gives them
* back, emptied, and wiring fails, changing nothing, when there are not two
* to take (counting those a port that is wired already would give back).
* The fabric allocates nothing.
*
* A fabric that was never given queues wires as it always did, and the
* operations on a node's wires answer that no one is on the port. That is
* how the fabrics of nothing that uses messages on the wire are made. */
void v4_fabric_queues(v4_fabric *f, v4_wire_queue *pool, unsigned count);
/* What is on the other end of a device's wire, put or taken as a whole
* message through the fabric. The device's side of `node`'s port `port`:
* put adds a message to those coming to the node, take removes the front
* message of those going from it. Each answers a V4_WIRE_ result, and
* V4_WIRE_NO_ONE when the port is not wired to a device. */
int v4_fabric_device_put(v4_fabric *f, unsigned node, unsigned port, const v4_cell *header7, const v4_cell *text);
int v4_fabric_device_take(v4_fabric *f, unsigned node, unsigned port, v4_cell *header7, v4_cell *text, unsigned text_cap);
/* A PORT WITH NOTHING ON IT. On the fabric a node that writes to such a
* port, or reads from it, waits for ever (docs/v4.0.0/MESH.md 4.1). That
* is so here for a bare node. But a node that can take an error is not
* left there: when it is blocked writing to, or reading from, one port that
* nothing is wired to -- because nothing ever was, or because what was
* there has been removed or the wire cut -- the error `code` is raised on
* it and it goes on (node.h, v4_node_port_gone). A node whose neighbour is
* asleep waits, and so does one reading "any port". With `code` 0, which
* is how a fabric begins, nothing is raised. */
void v4_fabric_gone_error(v4_fabric *f, v4_cell code);
/* A WORD NO ONE WILL READ. The same error is raised on a node that can take
* one and is blocked writing a word to a port whose other end will not read
* it: a device that takes no words (its `take` is 0: it speaks whole
* messages only), or a node that speaks whole messages -- one that has
* asked for a whole-message operation (below) since it was born, whatever
* it is doing now: asleep at its wires, running, stuck in a loop, or put to
* sleep by the fabric. Such a node does not read words, and before this a
* word written to one blocked its writer for ever (found by the final
* review of step 6e). A node that has asked for none yet may still read:
* the writer waits for it. That is a newborn node being sent its nucleus
* a word at a time, which executes from its ports and has asked nothing of
* a wire. */
/* THE WALK (mechanism A, docs/v4.0.0/plans/2026-11-17-the-fabric-step-cost.md). The places that hold
* a node, in ascending number: each pass of a step walks these, not every place, in the same order.
* v4_fabric_first gives the first, v4_fabric_next the one after `id` -- also when `id` has just been
* removed -- and each gives the capacity when there are no more. */
unsigned v4_fabric_first(const v4_fabric *f);
unsigned v4_fabric_next(const v4_fabric *f, unsigned id);
/* More room: `places`, of `capacity` no less than before, takes over; every
* node keeps its number and its wiring. */
void v4_fabric_grow(v4_fabric *f, v4_place *places, unsigned capacity);
/* A node is born (node.h, v4_node_born): empty, its ports at `port_base`,
* wired to nothing, awake and blocked reading its ports. Returns its
* number, or -1 if there is no room. */
int v4_fabric_add(v4_fabric *f, v4_fabric_node *storage, v4_cell port_base);
/* A node is removed, whatever it was doing. Every wire to it is cut; a
* neighbour blocked on one of them stays blocked, as it would on a port
* with nothing there. Returns the storage it was given, or 0. */
v4_fabric_node *v4_fabric_remove(v4_fabric *f, unsigned id);
/* The node numbered `id`, or 0 if there is none. */
v4_fabric_node *v4_fabric_node_at(const v4_fabric *f, unsigned id);
/* Wire port `pa` of node `a` to port `pb` of node `b`, or to a device; or
* cut whatever is on it. Whatever was on a port before is cut, at both
* ends. Each returns 1, or 0 if a node or a port is not there. */
int v4_fabric_wire(v4_fabric *f, unsigned a, unsigned pa, unsigned b, unsigned pb);
int v4_fabric_wire_device(v4_fabric *f, unsigned a, unsigned pa, const v4_device *device);
/* THE KERNEL ON A PORT (MESH.md 7d.5, ruled 2026-10-08). A node asks its
* kernel by words written to a port, and the kernel takes no messages: its
* port is wired to the device as above but is given no queues. Words are
* handed over as for any device; every operation on whole messages there
* answers that no one is on the port, so that a message sent to it is
* refused at once and nothing waits for it. */
int v4_fabric_wire_kernel(v4_fabric *f, unsigned a, unsigned pa, const v4_device *device);
int v4_fabric_unwire(v4_fabric *f, unsigned a, unsigned pa);
/* A node that is asleep executes nothing, and nothing is handed to it or
* taken from it. It can be put to sleep and woken at any instruction
* word. */
void v4_fabric_sleep(v4_fabric *f, unsigned id);
void v4_fabric_wake(v4_fabric *f, unsigned id);
/* WHOLE MESSAGES. A node that has stored an operation to Do (node.h) is
* blocked, and in the step in which it did the operation is done, whole, and
* the node is let go: put, take, move and drop and the rest (MESH.md 7d.3).
* Take, move and drop are done only on the message the node last looked at
* on that wire (wire.h, THE LOOK): if the mark is at any other -- the wire
* was cut and made again since -- they answer 3 and nothing is written.
* Sleep (8) and sleep for room (9) are the two that wait: the node stays
* blocked, executing nothing, until a message has come to one of its wires
* since it last fetched which wires have one. A message has "come" when a
* put or a move or a device put put it on the back of a queue; fetching Have
* clears that for all of the node's wires.
* SLEEP FOR ROOM (9) answers 0 at once if the wire it names has the room,
* and 1 at once if it can never have it. Otherwise the node sleeps until a
* message has come, as for 8, or a message has come off ANY of the wires
* that lead from it -- taken, moved on or dropped by whoever reads that wire
* -- since it was last woken that way, or one of its wires has been cut;
* then it is answered 0 if the wire it named now has the room and 1 if not,
* and it asks which wire has what (10). A node may be waiting to put on several wires at once and can name
* only one. A wake-up that finds nothing to do is answered by asking
* again.
*
* Time passes: every node that is awake and not blocked executes one
* instruction word; then every write with a reader waiting on the other end
* of its wire is handed over, and every device is asked. Returns how many
* instructions were executed and words handed over together: 0 means
* nothing can happen until something outside changes. */
unsigned v4_fabric_step(v4_fabric *f);
#endif /* V4_FABRIC_H */