Axle v0.22.0

Concept index

Every Axle keyword, type, annotation, and runtime guarantee on one page — with a link to the chapter that documents it. Use this when you know the concept name but don’t remember which section covers it.

Keywords and syntax

Keyword / constructDocumented in
let (immutable binding)Language tour → Variables
let mut (writable binding)Language tour → Variables
const (file-scope constant)Language tour → Variables
fn (free function)Language tour → Top-level declarations
class / traitLanguage tour → Top-level declarations · OOP recipe
class Foo : Base, Trait (unified supertype list)OOP recipe → Unified class header
dyn Trait (explicit trait-object receiver)OOP recipe → dyn Trait
Default trait method bodiesOOP recipe → Default method bodies
impl blocks (a type satisfies a trait without declaring it)OOP recipe → impl blocks
when T : Bound (conditional method group)OOP recipe → when T : Bound · Generics and traits
<T : A + B> generic boundsGenerics and traits → Generic bounds
match (value pattern match, exhaustive)Pattern matching · Language tour → Control flow
Patterns (literal, binding, range, or, struct, enum, null, _, const, guard)Pattern matching → The pattern kinds
match type T (compile-time type switch)Language tour → Control flow · Generics and traits → match type
@derive(Eq, Ord, Hashable, ToString, Clone)OOP recipe → @derive · Generics and traits → @derive
=> (the arm arrow in match, an impl-block arm, lambdas)Language tour → Control flow
(params) => expr (lambda / closure), (A) => R (its type)Language tour → Lambdas
enum (named integer tags, backing type, payloads, methods)Enums · Language tour → Top-level declarations
pub / pub(crate) / pub(file) / pub(derived) (visibility, on a field and a method; no marker = private on a class member, open on a struct or enum member) · readonly (member modifier)Language tour → Visibility and member modifiers
static field (one slot for the class, read Class::FIELD) · field : T = v on a class (initialiser)Language tour → Visibility and member modifiers
constructor / drop() (destructor)Shared<T> → Destructors
static fn (namespace-style method)FFI → static fn
:: (static / module access — Color::Red, Config::load)Language tour → Operators · Visibility and field modifiers
struct (value semantics)Language tour → Structs
copy a (a second, independent struct value) · own a (hand the value over)Structs: copy and own
clone() on a class (how copy duplicates an object)Structs: copy and own → A class says how it is copied
T { field } (field shorthand) · field : T = v (default) · ..base (spread)Language tour → Structs
f(name: value) (named argument)Language tour → Naming arguments at the call site
(A, B) tuple · t.0 element accessLanguage tour → Tuples
let (a, b) = … (destructuring binding)Language tour → Taking one apart
(w: T, h: U) (named tuple positions)Language tour → Naming the positions
if / else if / while / do-while / for / matchLanguage tour → Control flow
Operators + compound assigns (+= … ??= &&= \|\|=)Language tour → Operators
as (numeric cast) · is / !is (type test)Language tour → Operators
break / continueLanguage tour → Control flow
try / catch / finally / throw / ! (error set — propagation is implicit)Language tour → Exceptions · Error handling
exception (declare a throwable type)Language tour → Exceptions · Error handling
deferLanguage tour → Deferred cleanup · Memory model → defer
spawn / Future<T> / await / .isAlive()Language tour → Concurrency · Tasks and async → The two worlds
async fn / Future<T> / awaitThe async world
Thread::run(f, args…) (create + start) / Thread::create(f, args…) then t.run() / .join() / .isAlive()Tasks and async → The third backing
await all / Async::all (join a Future<T>[])The async world → Joining a set of futures
Async::sleep(ms) (cooperative delay)The async world
synchronized blockConventions → Concurrency idioms · Concurrency primitives → When you actually need a lock
use (module import)Language tour → Modules and imports · Conventions → Modules and use
extern "C" fn (import a symbol)FFI → extern “C” fn
extern "C" fn … { … } (export a symbol)Exporting to C
extern "C" struct / class (C layout)FFI → a layout you did not choose
extern "C" (A, B) => R (thin C function pointer)FFI → Callbacks
extern "C" from "lib" { … } (grouped imports)FFI → Grouping a file of bindings
sizeof<T>() / offsetof(T, field)FFI → Measuring it
unsafe { ... } blockFFI → unsafe blocks
new T(...)Memory model
share new T(...)Shared<T> → Allocating
new T[n] (a buffer of zeroed slots)Memory model → Allocating a buffer
unsafe { new unzeroed T[n] } (slots left unwritten)Memory model → Skipping the clearing
drop x; (release by hand)Memory model → Releasing by hand
share x, unshare s, downgrade s, upgrade wRefcount and transitions

Parameter prefixes

PrefixMeaningWhere
(none — borrowed)Borrowed reference; the borrow cannot escape the callMemory model → Ownership keywords
mutMutable in place; ownership stays with callerMemory model → Ownership keywords
ownConsumes the value; caller can’t use it after. A struct holding an array is passed copy a or own aMemory model → Ownership keywords · Structs: copy and own

Types

TypeDocumented in
Primitives (i8–i64, u8–u64, f32/f64, bool, char, string, void)Language tour → Primitive types
T[N] (fixed-size array)Language tour → Primitive types
T[] (dynamic array)Language tour → Primitive types · Collections recipe
Shared<T> (refcounted)Shared<T> reference counting
Future<T> (a handle on a result — stackful from spawn, coroutine from async fn)Tasks and async → The two worlds
ptr<T> / ptr (raw pointers)FFI → ptr
(A, B) / (w: A, h: B) (tuple, optionally named)Language tour → Tuples
Vector types f32x8, i32x4, …SIMD → Vector types
T \| null (nullable)Language tour → Nullable types · Shared<T> → Transitions
?. (safe navigation — the guard written inline)Language tour → Safe navigation

Annotations

AnnotationEffectWhere
@vectorize / @vectorize(width: N) / @vectorize(disable)Enable / pin / disable loop vectorisationSIMD → Auto-vectorisation · Annotations
@unroll(N)Pin loop unroll factorSIMD → @unroll · Annotations
@link(symbol = "symbol")Pin the C-side symbol when it differs from the Axle name — on an import or an exportFFI → extern “C” fn + @link(symbol = …) · Exporting → Choosing the symbol name
@layout(packed)Refuse the padding in an extern "C" record — a wire format or on-disk headerFFI → Measuring it
@upsert("probe" \| "slot_read" \| "slot_write" \| "lookup" \| "insert")Declare a container method’s part, so lookup-then-insert fuses to one probeLoop and idiom rewrites → Upsert fusion
@float(fast \| strict \| contract)Per-function float semantics: allow reassociation, forbid it, or allow contraction onlyAnnotations → @float
@inline(always) / @inline(never)Force a function into every caller, or keep it a callAnnotations → @inline
@heat(cold)Mark a function cold — never inlined, sized for size rather than speedAnnotations → @heat
@target(os = …, arch = …)The declaration exists only on the listed targetsProjects → When only one declaration differs

Memory tiers

TierWhen the compiler picks itDocumented in
StackProvably non-escaping new T(...)Memory model → Four tiers
ArenaEscapes its scope but not the functionMemory model → Four tiers
Heap (owned)Escapes the function with a single ownerMemory model → Four tiers
Shared (opt-in)You wrote share new T(...) or the binding type is Shared<T>Shared<T>
No allocationAn owned child provably living and dying with its parent is folded into itMemory placement → The cheapest tier is no allocation at all

SIMD operations

OperationSurface formWhere
Broadcast scalar to all lanesTx<L>.splat(v)SIMD → Operations
Literal-list constructorTx<L>(v0, v1, …)SIMD → Construction
Typed load / storeTx<L>.load(buf, i) (producer) / v.store(buf, i)SIMD → Operations
Fused multiply-adda.fma(b, c)SIMD → Operations
Horizontal reductionsv.sum() / v.max() / v.min()SIMD → Operations
Masked blendTx<L>.select(mask, a, b)SIMD → Operations
Lane permutationv.shuffle(indices)SIMD → Operations
Lane equalitya.eq(b)SIMD → Operations
Lane orderinga.lt(b) / a.gt(b)SIMD → Operations
Movemaskv.movemask()SIMD → Operations
Unsigned lanesu8x16 / u32x4 … (umax / udiv semantics)SIMD → Unsigned lanes
Vector arithmetica + b, a - b, a * b, a / b, a % bSIMD → Operations
Vector bitwise and shiftsa & b, a \| b, a ^ b, ~a, v << n, v >> n, v >>> nSIMD → Bitwise and shift operators

Standard library — by topic

TopicModule(s)Recipe
Lists / maps / setsstd/collectionsCollections
Exception classesstd/langError handling
Math + PRNGstd/numeric/math, std/numeric/randomNumeric and time
Time / date / sleepstd/time, std/time/datetimeNumeric and time
Strings, parsing, JSON, regex, hashingstd/text and submodulesStrings and text
File I/O, pathsstd/io, std/io/pathFiles and I/O
TCP / HTTP / DNSstd/net, std/net/dns—
Process, env, sysinfo, args, logstd/sys and submodulesCLI tools and system
Locks / atomics / channelsstd/concurrentConcurrency primitives
libc FFI helpers (sqrt, malloc, …)std/ffi/libm, std/ffi/libc/memFFI
Console typed I/Ostd/langevery recipe uses it

Error code ranges

RangeConcernWhere
E0001–E0021Typing, shape, naming, arity, unreachable codeReading compiler errors
E0281Ownership declaration (mut never mutated)Reading compiler errors
E0293–E0294Bounds analysisReading compiler errors
E0501–E0506Ownership flow lattice (use-after-move, double move, use after free)Reading compiler errors
E0509–E0510Concurrency (spawn borrow, a handle consumed twice)Reading compiler errors
E0511Closeable local without close()Reading compiler errors
E0517for … of iterable that is not a range, an array, or an iteration protocolReading compiler errors
E0740A constructor may leave a non-nullable heap field unassigned, or a class with such a field has no constructorStructs & value semantics
E0743–E0744Struct { … } literal omitting a field, or naming one twiceReading compiler errors
E0745Argument label not matching the parameter at its positionLanguage tour → Naming arguments
E0747..base of the wrong struct typeReading compiler errors
E0720File-scope const or static field whose initialiser is not a constant expression (a call, a cycle)Language tour → Variables
E0761== on a struct, tuple, array or SIMD vectorLanguage tour → Operators
E0779–E0786impl-block diagnostics (wrong header, generic trait, unknown/missing/duplicate method, duplicate target, non-concrete target, ambiguous method)Generics and traits → impl blocks
E0772=== on operands of two different typesLanguage tour → Operators
E0601Generic bound not satisfied at instantiation siteGenerics and traits → bounds
E0700, E0701, E0705Unimplemented features: a lambda capturing self or nested in a capturing lambda (E0700), an async { … } block (E0701), a nested type declaration (E0705). E0702–E0704 are unusedLanguage tour → Lambdas · Limits / Uncabled
E0707Raw-pointer op (deref / i64 ↔ ptr<T> cast) outside an unsafe { } blockFFI — unsafe blocks
E0708getUnchecked / setUnchecked, or an unchecked word access, outside an unsafe { } blockFFI — unchecked array access
E0787new unzeroed T[n] outside an unsafe { } blockReading compiler errors
E0763A word access whose buffer is not a byte-array variable or fieldFFI — word access
E0710–E0713spawn dispatchReading compiler errors
E0719, E0721–E0726, E0728–E0729, E0767, E0769Concurrency verbs + async structural gates + handle portability + an async fn reaching a frame that parks + a task outliving a value it borrowsReading compiler errors
E0738–E0739Async::all / await all operand and arityThe async world → Joining a set of futures
E0714–E0718SIMD method dispatchSIMD → Errors

Editor and tooling

TopicWhere
VS Code extension — install, features, status bar, tasksEditor support → VS Code
Customising semantic-token coloursEditor support → Customising colours
Built-in editor snippets (fn, class, try, …)Editor support → Snippets
axle build / run / check / bench as one-click tasksEditor support → Tasks
Driving axle-lsp from non-VS-Code editorsEditor support → Other editors

Compiler optimisations

These pages explain what the compiler does to your code without changing its observable behaviour — each lives next to the feature it backs:

OptimisationWhere
The map of what the compiler optimises (and what it won’t)Optimisations
Memory placement — the stack > arena > refcount > heap ladderMemory placement
Field inlining and alignment packing — one allocation instead of two, no padding between fieldsMemory placement → The cheapest tier is no allocation at all
Counting a run’s allocations (--alloc-stats)Memory placement → Counting what actually ran
Bounds-check elimination (between-variable + interprocedural)Bounds-check elimination
Escape analysis (stack / arena promotion)Escape analysis and promotion
Arithmetic strength reduction — constant/pow2 divide, hoisted divisor, guard elisionArithmetic strength reduction
memset / memcpy loop recognition, per-value range bounds elision, abs idiom, peepholes, dead-code eliminationLoop and idiom rewrites
Upsert fusion — a container’s lookup-then-insert collapsed to one probeLoop and idiom rewrites → Upsert fusion
Inline decisions + tail-call detectionInlining and tail calls · Inlining, tail calls, and whole-program merge
Whole-program merge (stdlib + hot runtime leaves into your module)Runtime and stdlib inlining
LLVM attributes / metadata the compiler stamps (noalias, !tbaa, !range, fast-math)What the compiler tells LLVM
Shared<T> header, atomic ordering, share / unshareRefcount and transitions
throw / catch dispatch modelException dispatch
CPU-level multi-versioning for FMA / reductionsSIMD CPU dispatch

See also

referenceindexkeywordsglossary