lib/alloc/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! The package decides which allocator a program's long-lived storage comes
 2 //! from, and it holds the byte ceiling a caller can put in front of an
 3 //! allocator. The single allocator a program's long-lived storage comes from,
 4 //! chosen when the program is compiled, is the *process allocator*. The parts
 5 //! of a program that live as long as the process take the storage they need
 6 //! while it starts up.
 7 //!
 8 //! The process sits in one stage of its life at a time, its *phase*, one of
 9 //! initialization, steady state, or teardown. The startup stage, in which
10 //! allocation is expected, is *initialization*. The call that ends
11 //! initialization and moves the process to steady state is the *seal*, executed
12 //! by `sealProcessAllocatorPhase`. The stage after the seal, in which an
13 //! allocation counts as a violation, is *steady state*. One allocator operation
14 //! that arrived in a phase which forbids it is a *violation*.
15 //!
16 //! The build setting that decides what happens to a violation, one of `off`,
17 //! `observe`, or `seal`, is the *process phase mode*. Under the `seal` build
18 //! setting, an allocation, a resize, or a remap that arrives after the seal
19 //! panics and is refused, and a free is refused the same way. Under the
20 //! `observe` setting, the same operation is counted, the return address of the
21 //! call that violated is kept as the *violation site*, and the operation goes
22 //! through. A free during teardown counts as no violation, so a program can
23 //! release its startup storage.
24 //!
25 //! The allocator that checks a byte ceiling of its own before asking the
26 //! allocator behind it for anything is the *limit allocator*, implemented as
27 //! `LimitAllocator`. That ceiling bounds how far the memory behind it can grow.
28 //! `LimitAllocator` reports its own refusal, `AllocationLimitExceeded`, apart
29 //! from the backing allocator's `OutOfMemory`, so a caller can tell a
30 //! configured ceiling from a machine running out of memory.
31 
32 const boundary = @import("boundary.zig");
33 const diagnostics = @import("diagnostics.zig");
34 const limit = @import("alloc_limit");
35 const locked = @import("alloc_locked");
36 const owner = @import("owner.zig");
37 const policy = @import("policy.zig");
38 const process = @import("process.zig");
39 
40 pub const phase = @import("alloc_phase");
41 
42 pub const TestAllocatorMode = policy.TestAllocatorMode;
43 pub const test_allocator_mode = policy.test_allocator_mode;
44 pub const allocator_diagnostics_mode = diagnostics.mode;
45 pub const ProcessPhaseMode = process.ProcessPhaseMode;
46 pub const process_phase_mode = process.mode;
47 
48 pub const longLivedProcessAllocator = policy.longLivedProcessAllocator;
49 pub const interactiveSessionAllocator = policy.interactiveSessionAllocator;
50 pub const standaloneProcessAllocator = policy.standaloneProcessAllocator;
51 pub const workerAllocator = policy.workerAllocator;
52 pub const threadedIoAllocator = policy.threadedIoAllocator;
53 pub const temporaryScratchAllocator = policy.temporaryScratchAllocator;
54 pub const testIntegrationAllocator = policy.testIntegrationAllocator;
55 
56 pub const diagnosticAllocatorConfig = diagnostics.config;
57 pub const diagnosticAllocatorReport = diagnostics.report;
58 
59 pub const sealProcessAllocatorPhase = policy.sealProcessAllocatorPhase;
60 pub const beginProcessAllocatorTeardown = policy.beginProcessAllocatorTeardown;
61 pub const processAllocatorPhase = process.currentPhase;
62 pub const processAllocatorPhaseViolations = process.violations;
63 pub const processAllocatorPhaseViolationSites = process.violationSites;
64 
65 pub const ProcessAllocatorOwner = owner.ProcessAllocatorOwner;
66 pub const ProcessAllocatorFinish = owner.ProcessAllocatorFinish;
67 pub const LimitAllocator = limit.LimitAllocator;
68 pub const LockedAllocator = locked.LockedAllocator;
69 
70 pub const PhaseBoundary = boundary.PhaseBoundary;
71 pub const PhaseBoundaryState = boundary.PhaseBoundaryState;
72 pub const writePhaseReport = boundary.writePhaseReport;