API reference: std

• std::alloc: Allocators over storage the program owns: FixedBuffer serves Alloc from a byte buffer (no heap, usable in realtime code), and bump_alloc is the step to build your own bump allocator handler.
• std::buf: Buf<T>, the growable buffer (Rust's Vec), and its algorithms: sort, search, retain, dedup. Growing asks for Alloc and destroying elements for Free; the index forms v[i], v[lo..hi], v.remove(i) require their index fact or use the _checked methods (Panic).
• std::bytes: Byte strings: searching, splitting, trimming and bounds-checked ranges over &[u8], the ASCII classes and case mappings of a byte and of &[u8], and decimal integers parsed from bytes and formatted into them. Reach for it on paths, protocol fields and a String's bytes (as_bytes) before or without UTF-8 validation. Nothing here panics: a bad range is None; only the copying case mappings allocate.
• std::cell: Cells for sharing between threads: OnceCell, set once and then read from any thread without a lock, and CachePadded, which keeps a value on cache lines of its own so threads writing neighbouring values do not slow each other down (false sharing).
• std::clone: Duplicating values: Clone. A copy value is duplicated by naming it; clone is for the rest, a value that owns memory (String, Box<T>), whose clone owns fresh memory of its own. Allocating is an effect, so clone asks for Alloc, which serves the region self is in: the clone lives where the original does. Buf, Deque and HashMap have no Clone yet: a loop of element clones is refused (R-Loan, decision 4488).
• std::cmp: Equality, ordering and hashing: Eq, Ord and Hash, the traits std::map and the sorted collections bound their keys by, with impls for the scalars, Box, Option, Buf, Str and &[u8], and named derives (impl Eq for Key = DeriveEq;) for your own types.
• std::deque: Deque, a double-ended queue: push and pop at both ends in amortised O(1), and index from the front. Pushing asks with Alloc because the ring may grow; nothing else allocates.
• std::env: The program's arguments and environment variables, read from the root's Env into Buf<u8>s (hence with Env, Alloc). They are bytes, as passed: an argument need not be UTF-8, and its as_bytes() is a path as it is. The environment is a snapshot taken at process start. In the simulated world (the library default, the playground) there are no arguments and no variables; a test installs its own Env handler with the ones it wants.
• std::errno: The errno std::fs, std::net and std::env answer in their Errs, named and formatted. They answer the kernel's word, a bare Int, so a match takes Err(2); wrapping it, Errno::new(e), gives its Display: strerror's text as glibc words it (No such file or directory), and Unknown error <n> for a number outside the table.
• std::fs: Files as an effect: code reaches the file system only through an Fs capability in its row, and only beneath the directory descriptors it is handed: every path is resolved beneath a dir: &Fd, and an absolute one or a .. that would leave it fails EXDEV (18). The root hands a program its first directory, cwd, and the program hands it on. Paths are bytes (&[u8]). Errors are the kernel's errno values (Err(Int)).
• std::fun: The closure traits, one per arity. A closure passed where a bound F: Fn(A) -> R is expected implements Fn1<A, R>; its body runs with no capabilities.
• std::heap: BinaryHeap, a priority queue: the greatest element by Ord (see std::cmp) is read in O(1) and removed in O(log n). Pushing asks with Alloc because the buffer may grow; nothing else allocates.
• std::io: Byte input by the line. Standard input is read through the root's Stdin (a prelude effect, beside Stdout and Stderr): Stdin.read(&mut b) copies the next bytes there are into b, and Stdin.read_line(&mut b) those up to and including the next \n, each answering the count, 0 at the end of the input. read_line and read_to_end append to a Buf<u8> instead (hence with Stdin, Alloc); the root buffers standard input, so a line is no system call. A socket or a file has no such buffer: a LineReader is one, for any source of bytes. The input is bytes, as given: a line need not be UTF-8, and String::from_utf8 validates one. In the simulated world (the library default, the playground, weir explore and weir test) standard input is empty; a test scripts it with std::sim::SimStdin.
• std::iter: Iteration: the Iterator pull trait, its adaptors and consumers, and integer ranges.
• std::lockfree: LockFreeMap, a fixed-size hash map many threads read and write at once without a lock. Every access goes through LockFreeMap::pin and the MapGuard it lends; removed entries are freed later, by LockFreeMap::collect, once no pinned thread can still see them.
• std::map: A hash map, HashMap, keyed by any K: Hash + Eq (see std::cmp). Methods that may grow the table ask for Alloc (new, with_capacity, insert); those that destroy entries ask for Free (remove, clear); lookups need no capability.
• std::memfs: An in-memory file system for tests: MemFs serves std::fs::Fs over the root's Loopback, whose file ops reach the simulated tree on every backend, interpreted and native, whatever the run's world. A #[test] installs it and runs a tool's with Fs code against files it made, the same way every time. The tree is empty when the run starts.
• std::net: Networking as an effect: code reaches sockets only through a Net capability in its row, so its caller's executor decides how each operation waits. Net includes std::task::Tasks (so Clock) and std::fs::Fs: one executor parks sleepers, tasks, socket ops and file ops in one table, and code written with Tasks, with Clock or with Fs runs in a Net task unchanged. close is Fs's, the one close of every descriptor. Install Evented or Blocking in main (they need the root's Reactor, Sys and Threads); a test uses std::sim::net_world.
• std::option: Option<T>'s methods. Option is the prelude's enum; its inherent methods are this module's, which every program loads, so o.is_none() needs no use. unwrap and expect are built-ins, not methods here; no method here can panic. The combinators take closures as std::iter's adapters do (F: Fn(T) -> U, std::fun): a closure literal there may borrow the enclosing locals, and its body runs with no capabilities, so these methods' rows are empty too. std::string prints an option as it is written, Some(3) or None.
• std::panic: Recovering from a panic: catch_panic runs a function and turns a panic inside it into an Err carrying the panic's message, after unwinding (destructors and guards run). Without it the root's Panic handler is terminal and a panic ends the program.
• std::rand: Randomness as an effect: code draws random numbers only through a Random capability, and fault points only through Draw, so its caller decides where the answers come from. The root supplies no Random: OsRandom draws the operating system's entropy through the root's Sys, std::sim::SimRandom is a seeded generator, and Calm answers every Draw the common way.
• std::result: Result<T, E>'s methods. Result is the prelude's enum; its inherent methods are this module's, which every program loads, so r.is_ok() needs no use. Only unwrap and expect can panic: their rows ask for Panic. The combinators take closures as std::iter's adapters do (F: Fn(T) -> U, std::fun), whose bodies run with no capabilities, so their rows are empty. std::string prints a result as it is written, Ok(3) or Err(e).
• std::retire: Retiring elements of a Buf into a caller's reclamation budget (Budget{Free}): the functions install a retire_from block over the budget, and its reclaimer destroys what they retire when the budget's owner destroys it. A budget with too few slots aborts the process.
• std::set: A hash set, HashSet, of any K: Hash + Eq (see std::cmp): the keys of a std::map::HashMap with no values. As there, methods that may grow the table ask for Alloc (new, with_capacity, insert), those that destroy keys ask for Free (remove, clear), and lookups need no capability.
• std::sim: Deterministic simulation for tests: handlers for std::time::Clock, std::rand::Random, std::rand::Draw, std::task::Tasks, std::net::Net, std::memfs::MemTree and the prelude's Stdin whose answers depend only on their arguments, so code that reaches time, randomness, tasks, the network, the disk and its input only through its row runs the same way every time. Start with world (tasks), net_world (network) or disk_world (disk).
• std::slice: Views of T slots: a Slice<T> is len slots of storage lent by its owner (Buf::slice, Buf::slice_mut), always behind & or &mut. The forms s[i], &mut s[i], s[i] = x, &s[lo..hi] and for x in s call these: the plain ones require the index fact, the _checked ones raise Panic instead.
• std::string: Text: String, an owned, growable UTF-8 string whose borrowed view is its bytes, &[u8]; Display, the trait a value formats itself into a String by; and print/println. Appending asks for Alloc (the string may grow), printing for Stdout; nothing here panics.
• std::sync: Waiting between tasks, over the executor's keys (std::task::Tasks's waker, park and wake): a task that waits is parked in its executor's table, never polling, and the task that wakes it readies it there. Both work under every executor (std::task::Pool, std::net's Evented and Blocking, std::sim's worlds). Under weir explore of a searched world every park is a scheduling point, and so is the start of every wait (Tasks.preempt()), where a wake-up from another thread can land between a check and the wait that depends on it.
• std::task: Concurrent tasks as an effect: code starts tasks only through a Tasks capability in its row, so its caller's executor decides where and when they run. A Tasks capability is also a std::time::Clock, so code written with Clock runs in a task unchanged. Use Pool in a program and std::sim::world (deterministic, one seed one schedule) in a test.
• std::test: Assertions for #[test]s and for any code that checks itself. Each failure is a Panic (raise), which fails the test. assert_eq and assert_ne format the two values by their Display impls into a String (hence Alloc in their rows; equal values allocate nothing) and panic through panic_detail: a handler of the Panic sees assert_eq failed, and the root's halt reads assert_eq failed: left 3, right 4. They take the values, as a call takes its arguments: a scalar, a Str or a byte view &[u8] is copied, and a value that owns memory is moved and dropped. Rust's #[should_panic] is written as a test that calls expect_panic.
• std::time: Time as an effect: code reads the clock and waits on it only through a Clock capability in its row, so its caller decides which clock it reads. Every executor (std::task::Pool, std::net::Evented) handles it with the monotonic clock in nanoseconds; a test uses std::sim::SimClock or the virtual time of std::sim::world.
• std::tuple: Tuples. The type (A, B) is [Tuple2<A, B>], up to (A, B, C, D, E, F), Tuple6: the surface writes (a, b) for a literal, t.0 for a field and (x, y) for a pattern, and every program loads this module, so none of those needs a use. A tuple is copy, forget or linear as its components are, and compares, orders and hashes field by field where its components do (std::cmp's derives), clones where they clone (std::clone), and std::string prints it as (a, b).

Reading the reference

Each entry shows a declaration as weir fmt writes it, then its doc comment. An effect's op has a control kind, which says what a handler's clause may do with the code that performed it:

• tail (an op written without a kind): the clause's result is the op's; the performer is never aborted or suspended.
• fallible: the clause resumes at once or aborts the with (abort(v)).
• raise: the clause never resumes; the perform unwinds to the handler's with.
• terminal: the clause halts the process; nothing is cleaned up.
• linear: the clause takes the continuation (cont k) and resumes it exactly once: a suspension.
• once: the clause takes the continuation and resumes or cancels it: a suspension and an abort edge.

A function of a package lists its committed interface: the lines of its entry in the module's .iface, which every caller outside the module is checked against (and its body must stay within). bound C: … lines give each capability parameter's bound (what the function may do through it); fact lines say what a call may do beyond its signature (aborts: the ops it may abort at, may diverge, scheduling point: where it may suspend, writes through, reads regions, destroys values of, holds, loan of); callback lines give each callback parameter's envelope (the capabilities it may use) and what the function does with it.