nub_flat/lib.rs
1//! The **flat** personality: nub's reference `Personality` /
2//! `GuestPersonality` pair.
3//!
4//! nub is personality-generic, and until now the only personality was
5//! JAVM — 2,700 lines of capability semantics, which makes it a poor
6//! answer to "what does a personality actually have to provide?". Flat
7//! is that answer: one program, one frame, no capability graph, no
8//! sub-VM calls, no yields. A program is published by content hash and
9//! invoked by content hash, and that is the whole object model.
10//!
11//! It exists for two reasons:
12//!
13//! 1. **It is the executable documentation.** The README's "Building a
14//! personality" section used to point at another repository.
15//! 2. **It makes nub's own JIT measurable.** Executing recompiled code
16//! needs the ring-0 substrate in `nub-arch-x86`, which needs a
17//! `GuestPersonality`. Without one, nub could measure how fast it
18//! *compiles* and never how fast the result *runs*.
19//!
20//! # Layout
21//!
22//! - [`hash`] — content addressing. `no_std`, shared by both halves.
23//! - the host half ([`Flat`], [`FlatLocal`]) — behind the `std` feature,
24//! which the guest build turns off.
25//! - the guest half — `nub-flat-guest-x86`, which links this crate with
26//! `default-features = false` for [`hash`].
27
28#![cfg_attr(not(feature = "std"), no_std)]
29
30extern crate alloc;
31
32pub mod hash;
33
34#[cfg(feature = "std")]
35mod local;
36
37#[cfg(feature = "std")]
38pub use local::FlatLocal;
39
40/// The flat personality.
41///
42/// Carries no state: everything it needs is in [`FlatLocal`] (host) or
43/// the guest's static store.
44#[cfg(feature = "std")]
45#[derive(Debug, Clone, Copy, Default)]
46pub struct Flat;
47
48#[cfg(feature = "std")]
49impl nub::Personality for Flat {
50 const NAME: &'static str = "flat";
51 type Local = FlatLocal;
52}