Module cpu_shared 

Shared-memory tasklet SDK surface (Phase 48.3 P3 + P3.1).

This module exposes the programmer-facing types for the shared-memory tasklet execution mode: a coordinator context, a worker context, typed views over the shared region and per-worker scratch, and partition helpers.

Dual implementation — one vocabulary

There are two concrete implementations of the public types (CoordinatorCtx, WorkerCtx, SharedRegion, WorkerScratch, SharedTaskletBuilder):

• host_mock — used on native host targets when the std feature is enabled. Runs coordinator + worker closures directly on host threads via std::thread::scope and std::sync::Barrier. This is the testing / prototyping path — it is NOT the runtime.
• [guest] — used when compiling for wasm32-unknown-unknown. Wraps the grafos_worker_v0 WASM imports in safe types. A program compiled through this path runs inside the real shared-memory tasklet runtime (P1 track) on a grafOS host.

A cfg-gated pub use below picks the right implementation for the current target, so programmers writing a tasklet import grafos_std::cpu_shared::{CoordinatorCtx, WorkerCtx, ...} without worrying about which target they’re building for. The public names are identical across both implementations.

Lifecycle difference (important)

The lifecycle of a shared-memory tasklet is not symmetric across targets, and this is reflected in how execution is kicked off:

• Host: the SDK initiates execution. Call FabricCpu::shared_memory_tasklet to obtain a SharedTaskletBuilder, configure it, then call .launch(coord_fn, worker_fn). The builder drives the closures on host threads.
• wasm32 guest: the runtime initiates execution. The guest module exports a tasklet_run(in_ptr, in_len, out_ptr, out_cap) -> i32 function that the runtime calls on every worker. Inside that export the guest calls [run_shared_memory_tasklet] with the same coordinator and worker closures. run_shared_memory_tasklet dispatches to the coordinator closure on worker 0 and the worker closure on workers 1..N, constructs the appropriate context from the linear-memory offsets published by grafos_worker_v0, and returns the i32 status.

The inner closures look identical on both targets — same CoordinatorCtx / WorkerCtx API, same partition helpers, same typed shared/scratch access. Only the entry-point shape differs.

Source portability (Phase 48.14)

Source-level portability between host mock and wasm32 guest is a documented, narrower subset of the promised behavioral portability. See the “Source portability” section of docs/grafos/shared-memory-tasklet-programming-model.md for the authoritative safe-list / cfg-list / behavior-divergent classification, and “Cross-target source patterns” in docs/grafos/shared-memory-tasklet-build-guide.md for the canonical #[cfg]-gated skeleton. Methods tagged with **Target-specific.** in their rustdoc are on the cfg-list; methods tagged with **Behavior diverges across targets.** compile on both targets but mean different things.

Programming model (host mock example)

use grafos_std::cpu::{CpuBuilder, CoordinatorCtx, WorkerCtx};
use std::sync::atomic::{AtomicU32, Ordering};

#[derive(Default)]
struct Shared {
    counter: AtomicU32,
}
#[derive(Default, Clone)]
struct Scratch {
    local: u32,
}

grafos_std::host::reset_mock();
let lease = CpuBuilder::new().cores(4).acquire().unwrap();
let _ = lease.cpu().shared_memory_tasklet::<Shared, Scratch>()
    .cores(4)
    .workers(4)
    .shared_bytes(1024)
    .scratch_bytes_per_worker(64)
    .fuel(1_000_000)
    .launch(|coord: &mut CoordinatorCtx<Shared, Scratch>| {
        coord.parallel_for_workers(|w| {
            w.scratch_mut().local = w.worker_index() as u32;
            w.shared().counter.fetch_add(1, Ordering::SeqCst);
        }).unwrap();
        let n = coord.shared().counter.load(Ordering::SeqCst);
        coord.set_output(&n.to_le_bytes());
        Ok(())
    });

Re-exports

pub use host_mock::Cancelled;

pub use host_mock::CoordinatorCtx;

pub use host_mock::FuelExhausted;

pub use host_mock::SharedRegion;

pub use host_mock::SharedTaskletBuilder;

pub use host_mock::SharedTaskletResult;

pub use host_mock::TaskletError;

pub use host_mock::WorkerCtx;

pub use host_mock::WorkerScratch;

Modules

host_mock

Shared-memory tasklet SDK surface — host mock (Phase 48.3 P3, Phase 48.14).

partition

Range/tile partition helpers for shared-memory tasklets.