==> include/mesh/jobs/frame.h <==1/* @ajax/mesh-jobs-frame: the job frames on the peer links (jobs.rs `Frame` and what it carries:
2 * `Prog`, `Held`, `LeaseMsg`, `ItemRes`, `RS_*`, `ST_*`, `HAVE_*`).
3 *
4 * On the wire a frame is its type (MESH_F_JOB_AVAIL .. MESH_F_RESULT), a u32 length, then the body,
5 * which starts with the leadership id it belongs to. A transfer in parts (ST_PART, F_JOB_HAVE)
6 * numbers them (`seq`) and its end says how many there were, so a part dropped on the way is never
7 * mistaken for a whole table (review finding 9). */
8#ifndef MESH_JOBS_FRAME_H
9#define MESH_JOBS_FRAME_H
10
11#include "mesh/jobs/id.h"
12#include "mesh/jobs/op.h"
13#include "mesh/jobs/ranges.h"
14#include "mesh/jobs/spec.h"
15#include "mesh/strbuf.h"
16
17#include <stdbool.h>
18#include <stddef.h>
19#include <stdint.h>
20
21/* An item's status in F_RESULT. */
22#define MESH_JOBS_RS_OK 0u
23#define MESH_JOBS_RS_FAIL 1u /* the task failed (R_JOB_FAIL, or the program faulted): `out` is the reason */
24#define MESH_JOBS_RS_RETURNED 2u /* not run (the program stopped, the lease was cut): back to the queue, no try counted */
25
26/* F_JOB_STATE kinds. */
27#define MESH_JOBS_ST_DELTA 1u
28#define MESH_JOBS_ST_PART 2u
29#define MESH_JOBS_ST_SNAP_END 3u
30#define MESH_JOBS_ST_REPLACE_END 4u
31#define MESH_JOBS_ST_COMMIT 5u
32
33/* F_JOB_HAVE's parts: the committed table (at its commit point), an entry not committed yet (its
34 * leadership and number), the end. */
35#define MESH_JOBS_HAVE_COMMITTED 1u
36#define MESH_JOBS_HAVE_DELTA 2u
37#define MESH_JOBS_HAVE_REPLACE 3u
38#define MESH_JOBS_HAVE_END 4u
39
40/* A job program running on a member (F_JOB_AVAIL). */
41typedef struct {
42 char *name;
43 uint32_t exec, cap;
44} mj_prog;
45
46/* A lease as its member holds it: the items it has not reported yet. */
47typedef struct {
48 uint64_t lease;
49 mj_job_id job;
50 char *program;
51 mj_ranges items;
52} mj_held;
53
54/* A lease as the leader sends it (self-contained: the member may not have the job's spec yet). */
55typedef struct {
56 uint64_t lease;
57 mj_job_id job;
58 char *program;
59 uint32_t op;
60 mj_setup *setup;
61 size_t nsetup;
62 mj_ranges items;
63} mj_lease_msg;
64
65typedef struct {
66 uint64_t lease;
67 mj_job_id job;
68 uint64_t item;
69 uint32_t status, result;
70 uint8_t *out;
71 size_t out_len;
72 bool has_blob;
73 mj_blob_ref blob;
74} mj_item_res;
75
76typedef struct {
77 uint8_t ty; /* MESH_F_JOB_AVAIL, _STATE, _ACK, _PULL, _HAVE, MESH_F_LEASE, _CUT, MESH_F_RESULT */
78 uint64_t lid;
79 mj_prog *progs; /* AVAIL */
80 size_t nprogs;
81 mj_held *held; /* AVAIL; HAVE when kind is HAVE_END */
82 size_t nheld;
83 uint32_t kind; /* STATE: ST_*; HAVE: HAVE_* */
84 uint64_t n, commit; /* STATE (n, commit); ACK (n) */
85 uint32_t seq; /* STATE, HAVE */
86 mj_ops ops; /* STATE; HAVE but HAVE_END */
87 bool gap; /* ACK */
88 uint64_t src0, src1; /* HAVE: the commit point (committed) or the entry's (leadership, number) */
89 mj_lease_msg l; /* LEASE */
90 uint64_t lease, cut; /* CUT */
91 mj_item_res *items; /* RESULT */
92 size_t nitems;
93} mj_frame;
94
95void mj_prog_free(mj_prog *p);
96mj_prog mj_prog_clone(const mj_prog *p);
97bool mj_prog_eq(const mj_prog *a, const mj_prog *b);
98bool mj_progs_eq(const mj_prog *a, size_t na, const mj_prog *b, size_t nb);
99mj_prog *mj_progs_clone(const mj_prog *p, size_t n);
100void mj_progs_free(mj_prog *p, size_t n);
101
102void mj_held_free(mj_held *h);
103mj_held mj_held_clone(const mj_held *h);
104bool mj_held_eq(const mj_held *a, const mj_held *b);
105
106void mj_lease_msg_free(mj_lease_msg *l);
107mj_lease_msg mj_lease_msg_clone(const mj_lease_msg *l);
108bool mj_lease_msg_eq(const mj_lease_msg *a, const mj_lease_msg *b);
109
110void mj_item_res_free(mj_item_res *r);
111mj_item_res mj_item_res_clone(const mj_item_res *r);
112bool mj_item_res_eq(const mj_item_res *a, const mj_item_res *b);
113
114void mj_frame_free(mj_frame *f);
115mj_frame mj_frame_clone(const mj_frame *f);
116bool mj_frame_eq(const mj_frame *a, const mj_frame *b);
117
118/* Constructors: they take ownership of the arrays and ops they're given. */
119mj_frame mj_frame_avail(uint64_t lid, mj_prog *progs, size_t nprogs, mj_held *held, size_t nheld);
120mj_frame mj_frame_state(uint64_t lid, uint32_t kind, uint64_t n, uint64_t commit, uint32_t seq, mj_ops ops);
121mj_frame mj_frame_ack(uint64_t lid, uint64_t n, bool gap);
122mj_frame mj_frame_pull(uint64_t lid);
123mj_frame mj_frame_have(uint64_t lid, uint32_t kind, uint32_t seq, uint64_t src0, uint64_t src1, mj_ops ops, mj_held *held, size_t nheld);
124mj_frame mj_frame_lease(uint64_t lid, mj_lease_msg l);
125mj_frame mj_frame_cut(uint64_t lid, uint64_t lease, uint64_t cut);
126mj_frame mj_frame_result(uint64_t lid, mj_item_res *items, size_t nitems);
127
128/* The wire bytes: type, u32 length, body. Appended to out. */
129void mj_frame_encode(const mj_frame *f, msb *out);
130/* A frame of type ty from its body (the bytes after the length); false with *err. */
131bool mj_frame_decode(uint8_t ty, const void *body, size_t n, mj_frame *out, char **err);
132
133/* The held leases' encoding (a u32 count, then each), shared with F_JOB_AVAIL and F_JOB_HAVE. */
134void mj_w_held(msb *w, const mj_held *h, size_t n);
135bool mj_rd_held(mj_rd *r, mj_held **h, size_t *n);
136
137#endif