tiny.sys.PulseControlStorage

1pub const ControlStorage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: ControlCapacity,4    bytes: []u8,56    pub const Limits: type = ControlLimits;7    pub const Capacity: type = ControlCapacity;8    pub const Exhaustion = error{ControlPayloadCapacityExceeded};9    pub const InitError = std.mem.Allocator.Error || error{CapacityOverflow};1011    pub const claim: alloc_phase.capacity.Declaration = .{12        .source = .{13            .id = "sys.pulse_control_storage",14            .kind = .phase_static,15            .limit_source = .caller,16            .storage = .{17                .covered = &.{18                    .{19                        .id = "one_reusable_pulseaudio_control_payload_region",20                        .lifetime = .steady,21                        .detail = "one reusable PulseAudio control payload region",22                    },23                },24                .excluded = &.{25                    "socket and kernel buffers, stream handles, and PulseAudio server state",26                    "caller-owned PCM frames and fixed frame-header stack values",27                    "process environment, cookie file handle, and fixed cookie stack bytes",28                },29            },30            .capacity = .{31                .inputs = &.{32                    alloc_phase.capacity.bindInput(ControlLimits, "inbound_control_payload_bytes", "inbound_control_payload_bytes"),33                    alloc_phase.capacity.bindInput(ControlLimits, "client_name_bytes", "client_name_bytes"),34                    alloc_phase.capacity.bindInput(ControlLimits, "channels", "channels"),35                },36                .type_selectors = &.{},37                .nodes = &.{38                    .{ .input = 0 },39                    .{ .input = 1 },40                    .{ .input = 2 },41                    .{ .scale = .{ .node = 2, .coefficient = .{ .literal = 4 } } },42                    .{ .add = .{ .left = 1, .right = 3 } },43                    .{ .maximum = .{ .left = 0, .right = 4 } },44                },45                .assertions = &.{.{46                    .scope = .closure_total,47                    .measure = .retained,48                    .relation = .exact,49                    .expression = 5,50                }},51            },52            .overload = .{53                .kind = .reject_before_mutation,54                .detail = "oversize payloads reject before reusable bytes mutate",55            },56            .risks = .{57                .transitive = .{58                    .status = .open,59                    .detail = "playback control traverses separate stream and environment owners",60                },61                .foreign = .{62                    .status = .open,63                    .detail = "control I/O enters socket, kernel, and PulseAudio server storage",64                },65            },66            .obligations = &.{67                .{ .key = "sys_pulse_control_capacity", .role = .capacity_model },68                .{ .key = "sys_pulse_control_oom_retry", .role = .custom },69                .{ .key = "sys_pulse_control_sealed", .role = .overload },70                .{ .key = "sys_pulse_control_semantics", .role = .custom },71                .{ .key = "sys_pulse_control_drain", .role = .custom },72            },73        },74        .bindings = .{75            .owner = @This(),76            .seal = .{77                .family = alloc_phase.capacity.selector(@This().activate),78                .premise = .{79                    .class = .checked_semantic_fact,80                    .authority = .checker,81                },82            },83            .teardown = .{84                .family = alloc_phase.capacity.selector(@This().deinit),85                .premise = .{86                    .class = .checked_semantic_fact,87                    .authority = .checker,88                },89            },90        },91    };9293    pub fn init(allocator: std.mem.Allocator, limits: ControlLimits) InitError!ControlStorage {94        const capacity = try ControlCapacity.derive(limits);95        const bytes = if (capacity.storage_bytes == 0)96            @as([]u8, &.{})97        else98            try allocator.alloc(u8, capacity.storage_bytes);99        return .{100            .phase = .initialization,101            .capacity = capacity,102            .bytes = bytes,103        };104    }105106    pub fn activate(self: *ControlStorage) void {107        std.debug.assert(self.phase == .initialization);108        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);109        self.phase = .steady;110    }111112    pub fn inbound(self: *ControlStorage, length: usize) Exhaustion![]u8 {113        std.debug.assert(self.phase != .teardown);114        if (length > self.capacity.inbound_control_payload_bytes) {115            return error.ControlPayloadCapacityExceeded;116        }117        return self.bytes[0..length];118    }119120    pub fn outbound(self: *ControlStorage, length: usize) Exhaustion![]u8 {121        std.debug.assert(self.phase != .teardown);122        if (length > self.capacity.outbound_control_payload_bytes) {123            return error.ControlPayloadCapacityExceeded;124        }125        return self.bytes[0..length];126    }127128    pub fn deinit(self: *ControlStorage, allocator: std.mem.Allocator) void {129        std.debug.assert(self.phase != .teardown);130        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);131        self.phase = .teardown;132        if (self.bytes.len != 0) allocator.free(self.bytes);133        self.bytes = &.{};134    }135};

1pub const PulseControlStorage = @import("pulse.zig").ControlStorage;