yog_event/
mirror.rs

1//! Mirrors (`docs/design/bus.md`, "Mirrors"): declaring one, providing one,
2//! its keys — services the runtime answers. A declaration's reply is where
3//! its data is: addresses in this process, read in place (`yog_mirror::view`).
4
5use yog_core::BlockPos;
6use yog_data::with::Raw;
7use yog_data::{Diagnostic, Schema};
8use yog_mirror::{MirrorSpec, Rate};
9
10/// Asks for `wanted` fields of mirror `spec` (a bit each, in its field
11/// order) at `rate`; they're written while the declaration lasts.
12#[derive(Debug, Clone, Schema)]
13pub struct Declare {
14    pub spec: MirrorSpec,
15    pub wanted: u64,
16    pub rate: Rate,
17    /// What its provider should cover (the mirror's scope type: a
18    /// [`BlockScope`]…); none when it covers everything.
19    pub scope: Option<Scope>,
20}
21
22/// A declaration's scope, as its mirror's scope type's Yog Data.
23#[derive(Debug, Clone, PartialEq, Eq, Schema)]
24pub struct Scope {
25    #[data(with = "Raw")]
26    pub bytes: Vec<u8>,
27}
28
29/// The blocks of a box (both corners in): the host's block mirror's scope.
30/// Its dimension is its key space's (`yog:keys/block/<dimension>`).
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Schema)]
32pub struct BlockScope {
33    pub min: BlockPos,
34    pub max: BlockPos,
35}
36
37/// Where a declared field's values are.
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Schema)]
39pub struct Place {
40    /// Its column (`*const YogColumn`).
41    pub column: u64,
42    /// How many parents up its column's key space is.
43    pub depth: u8,
44}
45
46/// A declaration made: its id (to release it) and where its data is.
47#[derive(Debug, Clone, PartialEq, Eq, Schema)]
48pub struct Declaration {
49    pub id: u32,
50    /// The mirror's key space (`*const YogKeySpace`).
51    pub space: u64,
52    /// The mirror's rows (`*const YogColumn`, a bit a space row).
53    pub rows: u64,
54    /// Each field's place, `None` when it wasn't asked for.
55    pub fields: Vec<Option<Place>>,
56}
57
58/// [`Declare`]'s answer: the declaration, or why there's none.
59#[derive(Debug, Clone, Schema)]
60pub struct Declared {
61    pub declaration: Option<Declaration>,
62    pub problem: Option<Diagnostic>,
63}
64
65/// Lets declaration `id` go.
66#[derive(Debug, Clone, Schema)]
67pub struct Release {
68    pub id: u32,
69}
70
71/// Makes the caller mirror `spec`'s provider. It answers the mirror's own
72/// address (`spec.name`) with a [`Write`] whenever fields are due; `host`:
73/// the game's own mirrors, first for every fact they write. The answer is
74/// what's wrong, if anything.
75#[derive(Debug, Clone, Schema)]
76pub struct Provide {
77    pub spec: MirrorSpec,
78    pub host: bool,
79    /// Its space is a family: a member each parameter
80    /// (`<space>/<parameter>`), made when it's first named, with this
81    /// mirror in it as `<name>/<parameter>`.
82    pub family: bool,
83}
84
85/// Mirror `name`'s provider saying it changed (its on-change fields are due).
86#[derive(Debug, Clone, Schema)]
87pub struct Touch {
88    pub name: String,
89}
90
91/// A key coming into a key space (`parent`: its key in the parent space).
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Schema)]
93pub struct Key {
94    pub key: u64,
95    pub parent: Option<u64>,
96}
97
98/// Keys coming into key space `space` and leaving it; the answer is the
99/// rows the new ones got.
100#[derive(Debug, Clone, Schema)]
101pub struct Keys {
102    pub space: String,
103    pub put: Vec<Key>,
104    pub take: Vec<u64>,
105}
106
107/// A provider's turn (sent to its mirror's address): the fields due, a
108/// bit each in its field order, and where they go.
109#[derive(Debug, Clone, Default, PartialEq, Eq, Schema)]
110pub struct Write {
111    /// The mirror's address (a family member's ends in its parameter).
112    pub mirror: String,
113    pub fields: u64,
114    /// The mirror's key space (`*const YogKeySpace`).
115    pub space: u64,
116    /// Its name (what [`Keys`] takes).
117    pub space_name: String,
118    /// The mirror's rows (`*const YogColumn`): a bit set a row it fills.
119    pub rows: u64,
120    /// The due fields' columns (`*const YogColumn`), in field order.
121    pub columns: Vec<u64>,
122    /// What the declarations asked it to cover.
123    pub scopes: Vec<Scope>,
124}
yog_event/mirror.rs

yog_event/
mirror.rs
