1/* @ajax/mesh-place-mode: a program's placement across a cluster of N machines (mesh-abi
2 * "placement"): local, pinned to one machine, or split by an assignment of its parts to systems; the
3 * request words that ask for one (`local`, `pin 2`, `split`, `split 0,1`, `split 1:3,2:1`,
4 * `split auto`); and each machine's role in a mode. */
5#ifndef MESH_PLACE_MODE_H
6#define MESH_PLACE_MODE_H
7
8#include "mesh/abi/placement.h"
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13
14/* A split's assignment: part b (task arg b, 0..fanout) is rendered by system of[b]. The owner
15 * (part 0's system) owns the state and applies the input. */
16typedef struct {
17    uint32_t fanout;
18    uint8_t of[MESH_PLACE_PARTS_MAX];
19} mpm_assign;
20
21mpm_assign mpm_assign_new(const uint32_t *of, size_t n);
22uint32_t mpm_owner(const mpm_assign *a);
23uint32_t mpm_mask_of(const mpm_assign *a, uint32_t sys); /* the parts sys renders */
24uint32_t mpm_members(const mpm_assign *a);               /* bit k: system k renders a part */
25char *mpm_list(const mpm_assign *a);                     /* "0,0,1,2" */
26/* count parts each, in the given order of systems (the first owns). */
27mpm_assign mpm_counts(const uint32_t *sys, const uint32_t *count, size_t n);
28/* The parts dealt over systems in order, contiguously, earlier systems taking the remainder; more
29 * systems than parts: the first fanout. */
30mpm_assign mpm_even(const uint32_t *systems, size_t n, uint32_t fanout);
31/* Weighted by time per part (ns; 0 unknown = the mean of the known): parts go one by one to the
32 * member that would finish them soonest; the fastest member owns, the others follow in order. */
33mpm_assign mpm_auto(const uint32_t *sys, const uint32_t *ns, size_t n, uint32_t fanout);
34bool mpm_assign_eq(const mpm_assign *a, const mpm_assign *b);
35
36uint32_t mpm_bits(uint32_t n); /* bits 0..n */
37
38typedef enum { MPM_LOCAL, MPM_PIN, MPM_SPLIT } mpm_kind;
39typedef struct {
40    mpm_kind kind;
41    uint32_t pin;   /* MPM_PIN */
42    mpm_assign a;   /* MPM_SPLIT */
43} mpm_mode;
44
45/* A request asks for a mode, or `split auto` over a member mask. */
46typedef struct {
47    bool is_auto;
48    mpm_mode mode;
49    uint32_t auto_mask;
50} mpm_target;
51
52mpm_mode mpm_local(void);
53mpm_mode mpm_pin(uint32_t k);
54mpm_mode mpm_split(mpm_assign a);
55bool mpm_mode_eq(const mpm_mode *a, const mpm_mode *b);
56bool mpm_target_eq(const mpm_target *a, const mpm_target *b);
57
58/* `local` | `pin k` | `split [spec]` for a cluster of n and a program of fanout parts. */
59bool mpm_parse(char *const *words, size_t nwords, uint32_t n, uint32_t fanout, mpm_target *out, char **err);
60/* (PLACE_*, the system it names: pin's runner, split's owner). */
61void mpm_code(const mpm_mode *m, uint32_t *code, uint32_t *sys);
62/* PX_PLACE_ASSIGN's bytes. */
63void mpm_assign_bytes(const mpm_mode *m, uint8_t out[MESH_PLACE_PARTS_MAX]);
64bool mpm_from_code(uint32_t code, uint32_t sys, const uint8_t *assign, size_t n, mpm_mode *out, char **err);
65char *mpm_label(const mpm_mode *m);
66/* Whether a manifest's `place` capability allows it. */
67bool mpm_allowed(const mpm_mode *m, uint32_t cap, char **err);
68/* Fits a cluster of n and a program of fanout parts. */
69bool mpm_fits(const mpm_mode *m, uint32_t n, uint32_t fanout, char **err);
70
71/* This machine's part in a mode. */
72typedef enum {
73    MPM_ROLE_LOCAL,    /* its own copy, nothing mirrored */
74    MPM_ROLE_RUNNER,   /* pinned here: runs every part, sends each frame to the others */
75    MPM_ROLE_MIRROR,   /* pinned elsewhere, or a split without parts here: shows the others' frames */
76    MPM_ROLE_OWNER,    /* split, part 0 here: owns the state, runs its parts */
77    MPM_ROLE_FOLLOWER, /* split, other parts here: runs them on the owner's state */
78} mpm_role;
79
80mpm_role mpm_role_of(const mpm_mode *m, uint32_t me);
81bool mpm_runs(mpm_role r); /* the kernel runs here */
82uint32_t mpm_input_to(const mpm_mode *m, uint32_t me); /* the machine that applies input */
83uint32_t mpm_parts_of(const mpm_mode *m, uint32_t sys, uint32_t fanout);
84/* The machine whose state continues across from -> to. */
85uint32_t mpm_authority(const mpm_mode *from, const mpm_mode *to);
86
87#endif