lib/alloc/phase/src/capacity/owner.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 /// Specifies the structural protocol expected of a memory owner across two
 2 /// independent axes: storage acquisition, defined by `StorageSource`, and
 3 /// exhaustion behavior, defined by `OverloadShape`. Four named constants
 4 /// represent the valid combinations: `allocator_exact`, `allocator_rejecting`,
 5 /// `provisioned_exact`, and `provisioned_rejecting`. This classification
 6 /// constrains required container declarations, field layouts, and lifecycle
 7 /// function signatures during compile-time shape validation. It does not
 8 /// inspect function bodies, verify that resource bounds are maintained at
 9 /// runtime, or prove the dynamic correctness of owner operations. An `exact`
10 /// classification indicates only that the shape contract requires no
11 /// steady-state exhaustion error. It does not promise that operational methods
12 /// are infallible or that runtime failures cannot occur.
13 pub const OwnerShape = struct {
14     storage_source: StorageSource,
15     overload_shape: OverloadShape,
16 
17     /// Selects the storage acquisition mechanism required during owner
18     /// initialization. The `allocator_backed` variant requires the owner's
19     /// `init` function to receive a standard `std.mem.Allocator` parameter. The
20     /// `caller_provisioned` variant requires `init` to receive an aligned slice
21     /// conforming to the owner's declared `Storage` type. The enumeration
22     /// defines structural initialization signatures only. Neither variant
23     /// enforces memory lifetimes or guarantees that callers retain backing
24     /// storage for the required duration of the owner.
25     pub const StorageSource = enum {
26         allocator_backed,
27         caller_provisioned,
28     };
29 
30     /// The exact overload shape requires no Exhaustion declaration. The
31     /// rejecting overload shape requires a finite nonempty Exhaustion error set
32     /// and at least one non-lifecycle pointer-receiver method whose return type
33     /// is an error set or error union containing all Exhaustion errors. The
34     /// return type does not have to be an error union. This signature check
35     /// does not prove error reachability.
36     pub const OverloadShape = enum {
37         exact,
38         rejecting,
39     };
40 
41     /// This shape value selects `allocator_backed` storage paired with an
42     /// `exact` overload surface. This identifier serves as a declaration value
43     /// describing the shape and does not run validation checks.
44     pub const allocator_exact: OwnerShape = .{
45         .storage_source = .allocator_backed,
46         .overload_shape = .exact,
47     };
48 
49     /// This shape value selects the pairing of `allocator_backed` storage with
50     /// a `rejecting` overload surface.
51     pub const allocator_rejecting: OwnerShape = .{
52         .storage_source = .allocator_backed,
53         .overload_shape = .rejecting,
54     };
55 
56     /// This shape value selects the pairing of `caller_provisioned` storage
57     /// with an `exact` overload surface.
58     pub const provisioned_exact: OwnerShape = .{
59         .storage_source = .caller_provisioned,
60         .overload_shape = .exact,
61     };
62 
63     /// This shape value selects the pairing of `caller_provisioned` storage
64     /// with a `rejecting` overload surface.
65     pub const provisioned_rejecting: OwnerShape = .{
66         .storage_source = .caller_provisioned,
67         .overload_shape = .rejecting,
68     };
69 };
70 
71 /// Defines three static bounds for owner lifecycle and maintenance work:
72 /// `transition_steps_max`, `cleanup_steps_per_call_max`, and
73 /// `cleanup_calls_at_capacity_max`. Structural validation requires
74 /// `transition_steps_max` to be greater than zero. The cleanup bounds must be
75 /// either both zero or both nonzero, and their arithmetic product must fit
76 /// within `usize` without overflow. These bounds are literal numeric
77 /// declarations checked solely for structural validity. Validation does not
78 /// measure CPU instructions, inspect loop constructs, or evaluate wall-clock
79 /// duration. In implementations providing cleanup routines, the work performed
80 /// by each cleanup step may depend on the extent of stored data rather than a
81 /// constant processing cost.
82 pub const WorkLimits = struct {
83     transition_steps_max: usize,
84     cleanup_steps_per_call_max: usize,
85     cleanup_calls_at_capacity_max: usize,
86 };