Struct World 

pub struct World {

    pub now: Timestamp,
    pub netwatch: Tracker,
    pub netwatch_failed: Option<String>,
    pub netwatch_stale: BTreeSet<UnitId>,
    pub wall_skew: i64,
    pub base_units: UnitDefs,
    pub base_user_units: Vec<UnitDef>,
    pub base_options: BTreeMap<String, Value>,
    pub base_packages: BTreeMap<String, String>,
    pub base_insecure: BTreeSet<String>,
    pub inject: BTreeMap<String, Injected>,
    pub base_inputs: BTreeMap<String, (String, String)>,
    pub rebuild_uid: u32,
    pub payload_at: Option<Timestamp>,
    pub rules: Vec<Rule>,
    pub forced: BTreeSet<String>,
    pub core_units: BTreeMap<String, Hash>,
    pub owner_files: BTreeMap<String, String>,
    pub untracked: BTreeSet<String>,
    pub gens: BTreeMap<GenerationId, Gen>,
    pub current: GenerationId,
    pub booted: GenerationId,
    pub boot_default: GenerationId,
    pub boot_entries: BTreeSet<GenerationId>,
    pub overrides: OverrideSet,
    pub override_store: BTreeMap<Hash, OverrideSet>,
    pub gen_overrides: BTreeMap<GenerationId, Hash>,
    pub staged: BTreeMap<String, (OverrideSet, BTreeMap<String, String>)>,
    pub gc_roots: BTreeSet<String>,
    pub collected: Vec<GenerationId>,
    pub fail_publish: bool,
    pub bad_drivers: BTreeSet<String>,
    pub edit_on_stage: bool,
    pub untracked_on_stage: Option<String>,
    pub nospace_on_build: bool,
    pub builds: usize,
    pub stages: usize,
    pub block_on_activate: BTreeSet<UnitId>,
    pub fail_activate: BTreeSet<GenerationId>,
    pub slow_activation: Option<(Millis, bool)>,
    pub jobs: BTreeMap<JobId, Job>,
    pub job_spans: BTreeMap<JobId, (Job, Timestamp, Option<Timestamp>)>,
    pub next_job: u64,
    pub jobs_tagged_unknown: bool,
    pub units: BTreeMap<UnitId, UnitSim>,
    pub devices: BTreeMap<UnitId, Option<DriverRef>>,
    pub sessions: Vec<SessionInfo>,
    pub compositors: BTreeMap<String, bool>,
    pub one_shot: Option<GenerationId>,
    pub fail_one_shot: bool,
    pub third_party_on_publish: bool,
    pub agent_instances: BTreeMap<String, InstanceId>,
    pub dry_activate_fails: Option<String>,
    pub hold_on_failure: BTreeSet<UnitId>,
    pub held: BTreeSet<UnitId>,
    pub hold_declines: BTreeSet<UnitId>,
    pub hold_hangs: Option<Millis>,
    pub lift_hangs: Option<Millis>,
    pub hold_wedged: BTreeSet<UnitId>,
    pub hold_released: BTreeMap<UnitId, Option<Timestamp>>,
    pub hold_fails: Option<String>,
    pub hold_table_flushed: bool,
    pub hold_table_unreadable: bool,
    pub hold_reapply_fails: bool,
    pub nar_mismatch: bool,
    pub probe_batch_ms: u64,
    pub activation_restarts: BTreeSet<UnitId>,
    pub next_instance: u64,
    pub third_party_override: Option<Hash>,
    pub foreign_units: Vec<String>,
    pub foreground: BTreeSet<String>,
    pub power: Option<PowerSource>,
    pub blocked: BTreeSet<UnitId>,
    pub external_down: BTreeSet<String>,
    pub external_unreachable: BTreeSet<String>,
    pub probe_batches: u64,
    pub fs: BTreeMap<String, (u64, u64)>,
    pub gc_budget: GcBudget,
    pub space_report: Option<SpaceReport>,
    pub runtime: BTreeMap<String, Value>,
    pub wifi_known: Vec<String>,
    pub wifi_in_range: BTreeSet<String>,
    pub alive: BTreeSet<u32>,
    pub unkillable: BTreeSet<u32>,
    pub calls: Vec<Call>,
}

Fields

now: Timestamp

netwatch: Tracker

What the kernel attributed to whom (gym step footprint).

netwatch_failed: Option<String>

The watch failed to attach, and why (gym step netwatch); None: attached, confirmed on every read.

netwatch_stale: BTreeSet<UnitId>

Units whose footprint has gone stale (gym step footprint_stale).

wall_skew: i64

Wall clock minus boot clock, in ms (set_wall_clock, §12h).

base_units: UnitDefs

The owner’s configuration as evaluated without any override.

base_user_units: Vec<UnitDef>

base_options: BTreeMap<String, Value>

base_packages: BTreeMap<String, String>

The base generation’s packages (pname → version) and the insecure ones (§12e).

base_insecure: BTreeSet<String>

inject: BTreeMap<String, Injected>

Outcomes to inject, by call name (restart, activate_live, …), once each.

base_inputs: BTreeMap<String, (String, String)>

The owner flake’s inputs, name → (rev, store path).

rebuild_uid: u32

Who the next out-of-band generation is created by (uid).

payload_at: Option<Timestamp>

When the bad payload takes gym-web’s port (set when a generation declaring it is applied).

rules: Vec<Rule>

forced: BTreeSet<String>

Options the owner mkForced.

core_units: BTreeMap<String, Hash>

owner_files: BTreeMap<String, String>

Tracked owner files (path → content) and untracked ones.

untracked: BTreeSet<String>

gens: BTreeMap<GenerationId, Gen>

current: GenerationId

booted: GenerationId

boot_default: GenerationId

boot_entries: BTreeSet<GenerationId>

overrides: OverrideSet

override_store: BTreeMap<Hash, OverrideSet>

gen_overrides: BTreeMap<GenerationId, Hash>

staged: BTreeMap<String, (OverrideSet, BTreeMap<String, String>)>

gc_roots: BTreeSet<String>

collected: Vec<GenerationId>

fail_publish: bool

bad_drivers: BTreeSet<String>

Drivers that bind but cannot drive the device.

edit_on_stage: bool

Hooks for faults that happen during a transaction: the owner edits a tracked file while staging; the store fills during the build; a port is blocked when the candidate activates.

untracked_on_stage: Option<String>

The owner adds this untracked file while staging (after the copy).

nospace_on_build: bool

builds: usize

How many times build ran.

stages: usize

Sources staged (§9 step 1), for admission-before-work checks (R09).

block_on_activate: BTreeSet<UnitId>

fail_activate: BTreeSet<GenerationId>

slow_activation: Option<(Millis, bool)>

jobs: BTreeMap<JobId, Job>

job_spans: BTreeMap<JobId, (Job, Timestamp, Option<Timestamp>)>

When each job started, and when it finished or was cancelled.

next_job: u64

jobs_tagged_unknown: bool

units: BTreeMap<UnitId, UnitSim>

devices: BTreeMap<UnitId, Option<DriverRef>>

sessions: Vec<SessionInfo>

compositors: BTreeMap<String, bool>

Whether the compositor runs in each session’s cgroup (§9); a session not listed falls back to the user’s graphical-session target.

one_shot: Option<GenerationId>

A generation published to boot once (§12f), and generations whose boot fails (the gym’s fail_boot).

fail_one_shot: bool

third_party_on_publish: bool

I23: a third party rewrites the override file once the next boot entry is published; the hash of what it wrote.

agent_instances: BTreeMap<String, InstanceId>

The running instance of each agent’s unit (I24), as the agent’s processes would show it in their cgroup.

dry_activate_fails: Option<String>

The next build’s dry activation fails this way (R10).

hold_on_failure: BTreeSet<UnitId>

§12d: network-security units whose failure holds traffic, as systemd’s OnFailure= on them starts planarian-hold@<unit> (nix/posture.nix).

held: BTreeSet<UnitId>

The units whose traffic is held now (/run/planarian/hold).

hold_declines: BTreeSet<UnitId>

Network tools the host declines to hold: not protecting (the hold unit’s condition skips, as for a tool with no footprint).

hold_hangs: Option<Millis>

A hold’s start takes this long (a slow or stuck systemctl start): every hold call gives up after its wait, the fake clock advanced by that much, and the hold lands later, as systemd’s job would.

lift_hangs: Option<Millis>

Like hold_hangs, for lift_hold alone (it takes precedence there): the table check and the holds still answer.

hold_wedged: BTreeSet<UnitId>

Units whose hold job is wedged: starting their hold never finishes (every hold for them times out, whatever its wait).

hold_released: BTreeMap<UnitId, Option<Timestamp>>

Released holds and until when (None: the next boot), as the /run/planarian/hold-released marker the hold script honours.

hold_fails: Option<String>

Fault injection: the next hold or lift fails this way.

hold_table_flushed: bool

Fault injection: something flushed the nftables ruleset, so the hold’s table is gone while holds are still in place (/run says held).

hold_table_unreadable: bool

Fault injection (§12d): the hold table cannot be checked (nft missing or failing).

hold_reapply_fails: bool

Fault injection (§12d): re-applying the hold fails (the table stays missing) while this is set.

nar_mismatch: bool

Fault injection (C6): the next candidate’s store contents no longer hash to the NAR hash recorded when it was built.

probe_batch_ms: u64

Each probe batch takes this long on the fake clock (P9’s slow tick).

activation_restarts: BTreeSet<UnitId>

Every candidate’s activation also restarts these (a user’s audio, say), so it disturbs an active session (§12f).

next_instance: u64

third_party_override: Option<Hash>

foreign_units: Vec<String>

Units planted outside the generation (the boot report finds them).

foreground: BTreeSet<String>

Sessions in which foreground work holds (§10 quiet mode).

power: Option<PowerSource>

blocked: BTreeSet<UnitId>

Probes of these units fail regardless (e.g. a port blocked by nftables).

external_down: BTreeSet<String>

External dependencies that are down, by name (gym-upstream).

external_unreachable: BTreeSet<String>

External dependencies whose traffic is dropped on the way (a dead gateway): their probes, and their clients’, time out.

probe_batches: u64

How many probe batches ran (a status request must not run one).

fs: BTreeMap<String, (u64, u64)>

Free bytes and size of filesystems, by path.

gc_budget: GcBudget

§12b bounds, and the last collection’s report. Each generation’s closure counts as GEN_BYTES, nothing shared.

space_report: Option<SpaceReport>

runtime: BTreeMap<String, Value>

wifi_known: Vec<String>

Wi-Fi: the networks NetworkManager knows, and those in range.

wifi_in_range: BTreeSet<String>

alive: BTreeSet<u32>

unkillable: BTreeSet<u32>

calls: Vec<Call>

Implementations

impl World

pub fn nar_of(path: &StorePath) -> Hash

The fake store’s NAR hash of a path.

pub fn dry_plan(&self, g: GenerationId) -> ActivationPlan

What switching from the current generation to g would do: the dry activation the real backend runs, from the two evaluations.

pub(crate) fn key(id: &UnitId) -> UnitId

pub fn override_hash_of(set: &OverrideSet) -> Hash

pub(crate) fn source_hash_of( files: &BTreeMap<String, String>, overrides: &OverrideSet, ) -> Hash

pub fn evaluate( &self, overrides: &OverrideSet, ) -> (EvaluatedGeneration, BTreeSet<UnitId>)

The fake evaluator.

pub fn add_generation(&mut self, overrides: &OverrideSet) -> GenerationId

pub fn apply_generation(&mut self, g: GenerationId)

pub fn on_failure_holds(&mut self)

§12d, OnFailure=: a failed network-security unit’s traffic is held, unless an unexpired release marks it.

pub fn advance_to(&mut self, now: Timestamp)

Advance time-driven behaviour to now.

pub fn stop_out_of_band(&mut self, unit: &UnitId)

systemctl stop outside Planarian: systemd also stops every unit that Requires= it (transitively).

pub fn kill(&mut self, unit: &UnitId)

SIGKILL a unit’s main process.

pub fn break_in(&mut self, g: GenerationId, unit: &UnitId)

Send sig to a unit’s main process, as systemctl kill does. SIGTERM, SIGINT, SIGHUP and SIGPIPE are clean exits to systemd (inactive); any other signal fails the unit. A flaw in generation g that shows only once it is live: the unit fails in g (and only there) from now on, and fails now if g runs.

pub fn signal(&mut self, unit: &UnitId, sig: i32)

pub fn oom(&mut self, unit: &UnitId)

The kernel’s OOM killer ends the unit (Result=oom-kill).

pub fn reboot(&mut self)

pub(crate) fn start(&mut self, id: &UnitId) -> Outcome

impl World

pub(crate) fn gc_plan( &self, protect: &[GenerationId], emergency: bool, ) -> GcPlan

Trait Implementations

impl Debug for World

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for World

fn default() -> World

Returns the “default value” for a type.