feat(registry): checkpoint PLN-0176 foundations and validated partial integrations
This commit is contained in:
@@ -0,0 +1,503 @@
|
||||
//! Session accounting shared by owners, with reservations refunded on failure/drop.
|
||||
//! These quotas account VM domains, not process RSS or allocator metadata.
|
||||
use std::collections::VecDeque;
|
||||
use std::fmt;
|
||||
use std::sync::{Arc, Mutex, MutexGuard};
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
#[repr(usize)]
|
||||
pub enum RuntimeResource {
|
||||
GuestBytes,
|
||||
HandleSlots,
|
||||
AuxiliaryBytes,
|
||||
TemporaryBytes,
|
||||
StringBytes,
|
||||
StringAllocations,
|
||||
IndividualStringBytes,
|
||||
CallDepth,
|
||||
}
|
||||
const COUNT: usize = 8;
|
||||
const MIB: u64 = 1_048_576;
|
||||
const CEILINGS: [u64; COUNT] =
|
||||
[256 * MIB, 1_048_576, 64 * MIB, 64 * MIB, 64 * MIB, 262_144, 4 * MIB, 1_024];
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct RuntimeLimits([u64; COUNT]);
|
||||
impl Default for RuntimeLimits {
|
||||
fn default() -> Self {
|
||||
Self(CEILINGS)
|
||||
}
|
||||
}
|
||||
impl RuntimeLimits {
|
||||
pub fn get(&self, resource: RuntimeResource) -> u64 {
|
||||
self.0[resource as usize]
|
||||
}
|
||||
/// Test/host configurations may lower ceilings; guest code cannot raise them.
|
||||
pub fn lowered(
|
||||
mut self,
|
||||
resource: RuntimeResource,
|
||||
limit: u64,
|
||||
) -> Result<Self, ResourceFailure> {
|
||||
if limit > self.get(resource) {
|
||||
return Err(ResourceFailure {
|
||||
resource,
|
||||
reason: ResourceReason::Limit,
|
||||
requested: limit,
|
||||
limit: self.get(resource),
|
||||
});
|
||||
}
|
||||
self.0[resource as usize] = limit;
|
||||
Ok(self)
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ResourceReason {
|
||||
Limit,
|
||||
SizeOverflow,
|
||||
AllocationFailed,
|
||||
}
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct ResourceFailure {
|
||||
pub resource: RuntimeResource,
|
||||
pub reason: ResourceReason,
|
||||
pub requested: u64,
|
||||
pub limit: u64,
|
||||
}
|
||||
impl fmt::Display for ResourceFailure {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
write!(
|
||||
f,
|
||||
"{:?}: {:?}, requested {}, limit {}",
|
||||
self.resource, self.reason, self.requested, self.limit
|
||||
)
|
||||
}
|
||||
}
|
||||
impl std::error::Error for ResourceFailure {}
|
||||
|
||||
#[derive(Debug)]
|
||||
struct State {
|
||||
limits: RuntimeLimits,
|
||||
used: [u64; COUNT],
|
||||
}
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct RuntimeBudget(Arc<Mutex<State>>);
|
||||
impl Default for RuntimeBudget {
|
||||
fn default() -> Self {
|
||||
Self::new(RuntimeLimits::default())
|
||||
}
|
||||
}
|
||||
impl RuntimeBudget {
|
||||
pub fn new(limits: RuntimeLimits) -> Self {
|
||||
Self(Arc::new(Mutex::new(State { limits, used: [0; COUNT] })))
|
||||
}
|
||||
fn state(&self) -> MutexGuard<'_, State> {
|
||||
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
|
||||
}
|
||||
pub fn used(&self, resource: RuntimeResource) -> u64 {
|
||||
self.state().used[resource as usize]
|
||||
}
|
||||
pub fn limit(&self, resource: RuntimeResource) -> u64 {
|
||||
self.state().limits.get(resource)
|
||||
}
|
||||
pub fn check(&self, resource: RuntimeResource, requested: u64) -> Result<(), ResourceFailure> {
|
||||
let limit = self.limit(resource);
|
||||
if requested > limit {
|
||||
Err(ResourceFailure { resource, reason: ResourceReason::Limit, requested, limit })
|
||||
} else {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
pub fn failure(
|
||||
&self,
|
||||
resource: RuntimeResource,
|
||||
reason: ResourceReason,
|
||||
requested: u64,
|
||||
) -> ResourceFailure {
|
||||
ResourceFailure { resource, reason, requested, limit: self.limit(resource) }
|
||||
}
|
||||
pub fn bytes<T>(
|
||||
&self,
|
||||
count: usize,
|
||||
resource: RuntimeResource,
|
||||
) -> Result<u64, ResourceFailure> {
|
||||
count
|
||||
.checked_mul(size_of::<T>())
|
||||
.and_then(|bytes| u64::try_from(bytes).ok())
|
||||
.ok_or_else(|| self.failure(resource, ResourceReason::SizeOverflow, u64::MAX))
|
||||
}
|
||||
pub fn reserve(
|
||||
&self,
|
||||
resource: RuntimeResource,
|
||||
amount: u64,
|
||||
) -> Result<Reservation, ResourceFailure> {
|
||||
let mut state = self.state();
|
||||
let current = state.used[resource as usize];
|
||||
let limit = state.limits.get(resource);
|
||||
let requested = current.checked_add(amount).ok_or(ResourceFailure {
|
||||
resource,
|
||||
reason: ResourceReason::SizeOverflow,
|
||||
requested: u64::MAX,
|
||||
limit,
|
||||
})?;
|
||||
if requested > limit {
|
||||
return Err(ResourceFailure {
|
||||
resource,
|
||||
reason: ResourceReason::Limit,
|
||||
requested,
|
||||
limit,
|
||||
});
|
||||
}
|
||||
state.used[resource as usize] = requested;
|
||||
Ok(Reservation { budget: self.clone(), resource, amount })
|
||||
}
|
||||
pub(crate) fn empty_charge(&self, resource: RuntimeResource) -> Reservation {
|
||||
Reservation { budget: self.clone(), resource, amount: 0 }
|
||||
}
|
||||
}
|
||||
|
||||
/// Unique accounting ownership; moving this token never charges a second time.
|
||||
#[derive(Debug)]
|
||||
pub struct Reservation {
|
||||
budget: RuntimeBudget,
|
||||
resource: RuntimeResource,
|
||||
amount: u64,
|
||||
}
|
||||
impl Reservation {
|
||||
pub fn amount(&self) -> u64 {
|
||||
self.amount
|
||||
}
|
||||
pub(crate) fn absorb(&mut self, mut other: Self) {
|
||||
assert!(Arc::ptr_eq(&self.budget.0, &other.budget.0));
|
||||
assert_eq!(self.resource, other.resource);
|
||||
self.amount += other.amount;
|
||||
other.amount = 0;
|
||||
}
|
||||
fn resize(&mut self, amount: u64) -> Result<(), ResourceFailure> {
|
||||
if amount > self.amount {
|
||||
self.absorb(self.budget.reserve(self.resource, amount - self.amount)?);
|
||||
} else {
|
||||
self.budget.state().used[self.resource as usize] -= self.amount - amount;
|
||||
self.amount = amount;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
impl Drop for Reservation {
|
||||
fn drop(&mut self) {
|
||||
self.budget.state().used[self.resource as usize] -= self.amount;
|
||||
}
|
||||
}
|
||||
|
||||
/// Scheduler storage owns its capacity charge, including unused capacity.
|
||||
/// During growth, the old allocation is also covered by a temporary reservation.
|
||||
#[derive(Debug)]
|
||||
pub(crate) struct BudgetQueue<T> {
|
||||
data: VecDeque<T>,
|
||||
charge: Reservation,
|
||||
}
|
||||
impl<T> BudgetQueue<T> {
|
||||
#[cfg(test)]
|
||||
pub(crate) fn capacity_bytes(&self) -> u64 {
|
||||
self.charge.amount
|
||||
}
|
||||
|
||||
pub fn new(budget: &RuntimeBudget) -> Self {
|
||||
Self { data: VecDeque::new(), charge: budget.empty_charge(RuntimeResource::AuxiliaryBytes) }
|
||||
}
|
||||
#[cfg(test)]
|
||||
pub fn len(&self) -> usize {
|
||||
self.data.len()
|
||||
}
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.data.is_empty()
|
||||
}
|
||||
pub fn pop_front(&mut self) -> Option<T> {
|
||||
self.data.pop_front()
|
||||
}
|
||||
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
|
||||
let b = &self.charge.budget;
|
||||
let q = RuntimeResource::AuxiliaryBytes;
|
||||
let required = self
|
||||
.data
|
||||
.len()
|
||||
.checked_add(additional)
|
||||
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
|
||||
if required <= self.data.capacity() {
|
||||
return Ok(());
|
||||
}
|
||||
// Exact growth prevents a geometric allocation from exceeding the available quota.
|
||||
let bytes = b.bytes::<T>(required, q)?;
|
||||
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
|
||||
let _temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
|
||||
let mut candidate = VecDeque::new();
|
||||
candidate
|
||||
.try_reserve_exact(required)
|
||||
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
|
||||
let actual = b.bytes::<T>(candidate.capacity(), q)?;
|
||||
// If the allocator reports excess capacity, reject before publishing the new buffer.
|
||||
extra.resize(actual - self.charge.amount)?;
|
||||
candidate.append(&mut self.data);
|
||||
self.data = candidate;
|
||||
self.charge.absorb(extra);
|
||||
Ok(())
|
||||
}
|
||||
pub fn push_back(&mut self, value: T) -> Result<(), ResourceFailure> {
|
||||
self.reserve(1)?;
|
||||
self.data.push_back(value);
|
||||
Ok(())
|
||||
}
|
||||
pub fn insert(&mut self, index: usize, value: T) -> Result<(), ResourceFailure> {
|
||||
self.reserve(1)?;
|
||||
self.data.insert(index, value);
|
||||
Ok(())
|
||||
}
|
||||
pub fn partition_point(&self, predicate: impl FnMut(&T) -> bool) -> usize {
|
||||
self.data.partition_point(predicate)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use RuntimeResource::*;
|
||||
|
||||
#[test]
|
||||
fn accepted_limits_are_fixed_and_can_only_be_lowered() {
|
||||
let limits = RuntimeLimits::default();
|
||||
for (resource, expected) in [
|
||||
(GuestBytes, 268_435_456),
|
||||
(HandleSlots, 1_048_576),
|
||||
(AuxiliaryBytes, 67_108_864),
|
||||
(TemporaryBytes, 67_108_864),
|
||||
(StringBytes, 67_108_864),
|
||||
(StringAllocations, 262_144),
|
||||
(IndividualStringBytes, 4_194_304),
|
||||
(CallDepth, 1_024),
|
||||
] {
|
||||
assert_eq!(limits.get(resource), expected);
|
||||
assert!(limits.clone().lowered(resource, expected + 1).is_err());
|
||||
assert_eq!(limits.clone().lowered(resource, 0).unwrap().get(resource), 0);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn shared_reservations_refund_on_failure_and_follow_their_owner() {
|
||||
let budget = RuntimeBudget::new(RuntimeLimits::default().lowered(GuestBytes, 10).unwrap());
|
||||
let charge = budget.reserve(GuestBytes, 7).unwrap();
|
||||
let shared = budget.clone();
|
||||
let failure = shared.reserve(GuestBytes, 4).unwrap_err();
|
||||
assert_eq!((failure.resource, failure.requested, failure.limit), (GuestBytes, 11, 10));
|
||||
assert_eq!(budget.used(GuestBytes), 7);
|
||||
let transferred = charge;
|
||||
assert_eq!(shared.used(GuestBytes), 7);
|
||||
let tail = shared.reserve(GuestBytes, 3).unwrap();
|
||||
assert_eq!(shared.used(GuestBytes), 10);
|
||||
drop(transferred);
|
||||
assert_eq!(shared.used(GuestBytes), 3);
|
||||
drop(tail);
|
||||
assert_eq!(shared.used(GuestBytes), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn queue_capacity_is_retained_until_drop_and_transfer_does_not_charge_twice() {
|
||||
let budget =
|
||||
RuntimeBudget::new(RuntimeLimits::default().lowered(AuxiliaryBytes, 16).unwrap());
|
||||
let mut queue = BudgetQueue::<u64>::new(&budget);
|
||||
queue.push_back(11).unwrap();
|
||||
queue.push_back(22).unwrap();
|
||||
assert_eq!(budget.used(AuxiliaryBytes), 16);
|
||||
assert!(queue.push_back(33).is_err());
|
||||
assert_eq!(queue.pop_front(), Some(11));
|
||||
assert_eq!(budget.used(AuxiliaryBytes), 16);
|
||||
queue.push_back(44).unwrap(); // reuse retained capacity
|
||||
let mut moved = queue;
|
||||
assert_eq!(budget.used(AuxiliaryBytes), 16);
|
||||
assert_eq!(moved.pop_front(), Some(22));
|
||||
assert_eq!(moved.pop_front(), Some(44));
|
||||
drop(moved);
|
||||
assert_eq!(budget.used(AuxiliaryBytes), 0);
|
||||
assert_eq!(budget.used(TemporaryBytes), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn temporary_growth_refusal_keeps_old_buffer_and_refunds_provisional_charge() {
|
||||
let limits = RuntimeLimits::default()
|
||||
.lowered(AuxiliaryBytes, 16)
|
||||
.unwrap()
|
||||
.lowered(TemporaryBytes, 0)
|
||||
.unwrap();
|
||||
let budget = RuntimeBudget::new(limits);
|
||||
let mut queue = BudgetQueue::<u64>::new(&budget);
|
||||
queue.push_back(11).unwrap();
|
||||
let error = queue.push_back(22).unwrap_err();
|
||||
assert_eq!((error.resource, error.requested), (TemporaryBytes, 8));
|
||||
assert_eq!(budget.used(AuxiliaryBytes), 8);
|
||||
assert_eq!(queue.pop_front(), Some(11));
|
||||
assert_eq!(queue.pop_front(), None);
|
||||
assert_eq!(budget.used(TemporaryBytes), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn size_and_length_overflow_fail_before_growth() {
|
||||
let budget = RuntimeBudget::default();
|
||||
assert_eq!(
|
||||
budget.bytes::<u64>(usize::MAX, AuxiliaryBytes).unwrap_err().reason,
|
||||
ResourceReason::SizeOverflow
|
||||
);
|
||||
let mut queue = BudgetQueue::<u64>::new(&budget);
|
||||
queue.push_back(11).unwrap();
|
||||
assert_eq!(queue.reserve(usize::MAX).unwrap_err().reason, ResourceReason::SizeOverflow);
|
||||
assert_eq!(budget.used(AuxiliaryBytes), 8);
|
||||
assert_eq!(queue.pop_front(), Some(11));
|
||||
}
|
||||
}
|
||||
|
||||
/// Contiguous execution storage. The capacity reservation travels with the buffer
|
||||
/// when a coroutine suspends/resumes, and is refunded only when storage is dropped.
|
||||
#[derive(Debug)]
|
||||
pub struct BudgetVec<T> {
|
||||
data: Vec<T>,
|
||||
charge: Reservation,
|
||||
}
|
||||
impl<T> BudgetVec<T> {
|
||||
pub fn new(budget: &RuntimeBudget, resource: RuntimeResource) -> Self {
|
||||
Self { data: Vec::new(), charge: budget.empty_charge(resource) }
|
||||
}
|
||||
pub(crate) fn prepare_growth(
|
||||
&self,
|
||||
additional: usize,
|
||||
) -> Result<Option<VecGrowth<T>>, ResourceFailure> {
|
||||
let b = &self.charge.budget;
|
||||
let q = self.charge.resource;
|
||||
let required = self
|
||||
.data
|
||||
.len()
|
||||
.checked_add(additional)
|
||||
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
|
||||
if required <= self.data.capacity() {
|
||||
return Ok(None);
|
||||
}
|
||||
let bytes = b.bytes::<T>(required, q)?;
|
||||
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
|
||||
let temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
|
||||
let mut candidate = Vec::new();
|
||||
candidate
|
||||
.try_reserve_exact(required)
|
||||
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
|
||||
extra.resize(b.bytes::<T>(candidate.capacity(), q)? - self.charge.amount)?;
|
||||
Ok(Some(VecGrowth {
|
||||
candidate,
|
||||
extra,
|
||||
_temporary: temporary,
|
||||
old_capacity: self.data.capacity(),
|
||||
}))
|
||||
}
|
||||
pub(crate) fn commit_growth(&mut self, growth: Option<VecGrowth<T>>) {
|
||||
if let Some(mut growth) = growth {
|
||||
assert_eq!(self.data.capacity(), growth.old_capacity);
|
||||
growth.candidate.append(&mut self.data);
|
||||
self.data = growth.candidate;
|
||||
self.charge.absorb(growth.extra);
|
||||
}
|
||||
}
|
||||
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
|
||||
let growth = self.prepare_growth(additional)?;
|
||||
self.commit_growth(growth);
|
||||
Ok(())
|
||||
}
|
||||
pub(crate) fn accounted_bytes(&self) -> u64 {
|
||||
self.charge.amount
|
||||
}
|
||||
pub(crate) fn from_slice(
|
||||
budget: &RuntimeBudget,
|
||||
resource: RuntimeResource,
|
||||
values: &[T],
|
||||
) -> Result<Self, ResourceFailure>
|
||||
where
|
||||
T: Clone,
|
||||
{
|
||||
let mut result = Self::new(budget, resource);
|
||||
result.reserve(values.len())?;
|
||||
result.data.extend_from_slice(values);
|
||||
Ok(result)
|
||||
}
|
||||
pub fn push(&mut self, value: T) -> Result<(), ResourceFailure> {
|
||||
self.reserve(1)?;
|
||||
self.data.push(value);
|
||||
Ok(())
|
||||
}
|
||||
pub fn resize(&mut self, len: usize, value: T) -> Result<(), ResourceFailure>
|
||||
where
|
||||
T: Clone,
|
||||
{
|
||||
self.reserve(len.saturating_sub(self.data.len()))?;
|
||||
self.data.resize(len, value);
|
||||
Ok(())
|
||||
}
|
||||
pub fn pop(&mut self) -> Option<T> {
|
||||
self.data.pop()
|
||||
}
|
||||
pub fn clear(&mut self) {
|
||||
self.data.clear();
|
||||
}
|
||||
pub fn truncate(&mut self, len: usize) {
|
||||
self.data.truncate(len);
|
||||
}
|
||||
pub fn capacity(&self) -> usize {
|
||||
self.data.capacity()
|
||||
}
|
||||
pub fn as_slice(&self) -> &[T] {
|
||||
&self.data
|
||||
}
|
||||
pub fn drain(&mut self, range: impl std::ops::RangeBounds<usize>) -> std::vec::Drain<'_, T> {
|
||||
self.data.drain(range)
|
||||
}
|
||||
pub fn take(&mut self) -> Self {
|
||||
let empty = Self::new(&self.charge.budget, self.charge.resource);
|
||||
std::mem::replace(self, empty)
|
||||
}
|
||||
/// Only used with the bounded native result writer after reserving its result slots.
|
||||
pub(crate) fn native_result_buffer(&mut self) -> &mut Vec<T> {
|
||||
&mut self.data
|
||||
}
|
||||
#[cfg(test)]
|
||||
pub(crate) fn fixture(data: Vec<T>) -> Self {
|
||||
let budget = RuntimeBudget::default();
|
||||
let bytes = budget.bytes::<T>(data.capacity(), RuntimeResource::AuxiliaryBytes).unwrap();
|
||||
let charge = budget.reserve(RuntimeResource::AuxiliaryBytes, bytes).unwrap();
|
||||
Self { data, charge }
|
||||
}
|
||||
}
|
||||
impl<T> std::ops::Deref for BudgetVec<T> {
|
||||
type Target = [T];
|
||||
fn deref(&self) -> &[T] {
|
||||
&self.data
|
||||
}
|
||||
}
|
||||
impl<T> std::ops::DerefMut for BudgetVec<T> {
|
||||
fn deref_mut(&mut self) -> &mut [T] {
|
||||
&mut self.data
|
||||
}
|
||||
}
|
||||
impl<'a, T> IntoIterator for &'a BudgetVec<T> {
|
||||
type Item = &'a T;
|
||||
type IntoIter = std::slice::Iter<'a, T>;
|
||||
fn into_iter(self) -> Self::IntoIter {
|
||||
self.data.iter()
|
||||
}
|
||||
}
|
||||
#[cfg(test)]
|
||||
impl<T: PartialEq> PartialEq<Vec<T>> for BudgetVec<T> {
|
||||
fn eq(&self, other: &Vec<T>) -> bool {
|
||||
&self.data == other
|
||||
}
|
||||
}
|
||||
|
||||
/// Unpublished growth can be dropped to refund every provisional reservation.
|
||||
pub(crate) struct VecGrowth<T> {
|
||||
candidate: Vec<T>,
|
||||
extra: Reservation,
|
||||
_temporary: Reservation,
|
||||
old_capacity: usize,
|
||||
}
|
||||
Reference in New Issue
Block a user