Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust
Rust ai-agentsai-toolsbrowserbrowser-automationcloud-browserheadlessheadless-browserkitesurfplaywrightpuppeteerrustservoweb-crawlerweb-crawlingweb-scraperweb-scraping
feat(parkable-image): add managed encoded image parking
ldm00099465abc98
diff --git a/Cargo.lock b/Cargo.lockindex c301eff2a..b97087d36 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -2901,6 +2901,14 @@ dependencies = ["peniko",]+[[package]]+name = "moli-parkable-image"+version = "0.1.0"+dependencies = [+ "moli-disk-pool",+ "parking_lot",+]+[[package]]name = "moli-parser"version = "0.1.0"diff --git a/Cargo.toml b/Cargo.tomlindex bc49ac763..3e72a25b6 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -40,6 +40,7 @@ members = ["moli-parser","moli-paint","moli-page-types",+ "moli-parkable-image","moli-process-signal","moli-renderer-v8","moli-robots",diff --git a/moli-parkable-image/Cargo.toml b/moli-parkable-image/Cargo.tomlnew file mode 100644index 000000000..5a46dad70--- /dev/null+++ b/moli-parkable-image/Cargo.toml@@ -0,0 +1,15 @@+[package]+license.workspace = true+name = "moli-parkable-image"+version = "0.1.0"+edition = "2024"++[dependencies]+moli-disk-pool = { path = "../moli-disk-pool" }+parking_lot = "0.12"++[dev-dependencies]+moli-disk-pool = { path = "../moli-disk-pool", features = ["test-support"] }++[lints]+workspace = truediff --git a/moli-parkable-image/README.md b/moli-parkable-image/README.mdnew file mode 100644index 000000000..87cf2f6c2--- /dev/null+++ b/moli-parkable-image/README.md@@ -0,0 +1,36 @@+# moli-parkable-image++Shared storage for completed encoded image bytes.+It releases idle buffers from memory by parking them in [`moli-disk-pool`](../moli-disk-pool/README.md), then restores them when a reader needs them.+The renderer shares this backing between image consumers and network records.++## What it does++- `from_frozen_bytes(Vec<u8>)` takes ownership of a completed buffer. Snapshots provide read-only access and prevent its memory from being discarded while readers are active.+- Parking writes one extent per image. Reading a parked image restores its bytes; the disk backup remains, so parking again needs no additional write.+- A manager tracks deadlines and separates resident from parked images. Defaults are a 1 KiB minimum size, a 30-second initial delay, and a 2-second delay after the last snapshot is released.+- `park_images()` respects those delays; `force_park_images()` bypasses them and immediately retries parking. Neither waits for a deadline or discards bytes held by live snapshots.+- The owning runtime drives scheduling. This crate creates no threads or timers; constructing a manager alone does not start automatic parking.++## Trade-offs++- `Arc<Vec<u8>>` adopts the receive buffer without a full payload copy, but retains its spare capacity until parking.+- Only completed encoded bytes are managed. Receive buffers and decoded RGBA/SVG data remain outside this crate.+- Unparking synchronously reads the whole image, even for a partial read. Retaining the disk backup uses space but makes later parking cheap.+- Failed parking keeps the bytes in memory; failed unparking returns an I/O error. Releasing a heap buffer does not guarantee an immediate RSS reduction, particularly with allocator retention or tmpfs.++## Examples++These use synthetic bytes; no decoder is involved.++- [`park_unpark.rs`](examples/park_unpark.rs): park manually, then restore through a snapshot.+- [`reader_leases.rs`](examples/reader_leases.rs): show why snapshots prevent parking but cloned image handles do not.+- [`deadline.rs`](examples/deadline.rs): customize the policy and drive one deadline. This is a single-threaded demonstration, not a concurrent scheduler.++Run from the repository root:++```sh+cargo run -p moli-parkable-image --example park_unpark+cargo run -p moli-parkable-image --example reader_leases+cargo run -p moli-parkable-image --example deadline+```diff --git a/moli-parkable-image/examples/deadline.rs b/moli-parkable-image/examples/deadline.rsnew file mode 100644index 000000000..d78b9993e--- /dev/null+++ b/moli-parkable-image/examples/deadline.rs@@ -0,0 +1,30 @@+//! Drive one parking deadline with a custom policy and synthetic image bytes.+//!+//! Run with `cargo run -p moli-parkable-image --example deadline`.+//!+//! This single-threaded, one-shot wait is not a concurrent scheduler.+//! Concurrent owners must also react to new_with_schedule_wakeup() notifications.++use std::time::{Duration, Instant};++use moli_disk_pool::DiskPool;+use moli_parkable_image::{ParkableImageManager, ParkableImagePolicy};++fn main() -> std::io::Result<()> {+ let policy = ParkableImagePolicy {+ parking_delay: Duration::from_millis(10),+ ..ParkableImagePolicy::default()+ };+ let manager = ParkableImageManager::new(Some(DiskPool::new(None)?), policy);+ let image = manager.from_frozen_bytes(vec![3; 4096]);++ let deadline = manager.next_parking_deadline().expect("image is eligible");+ std::thread::sleep(deadline.saturating_duration_since(Instant::now()));+ manager.park_images();++ assert_eq!(image.retained_memory_bytes(), 0);+ assert_eq!(manager.diagnostics().parked_count, 1);+ assert!(manager.next_parking_deadline().is_none());+ println!("Parked the image at its deadline; no further deadline is scheduled.");+ Ok(())+}diff --git a/moli-parkable-image/examples/park_unpark.rs b/moli-parkable-image/examples/park_unpark.rsnew file mode 100644index 000000000..4f7c8c9ef--- /dev/null+++ b/moli-parkable-image/examples/park_unpark.rs@@ -0,0 +1,30 @@+//! Park synthetic image bytes and restore them through a snapshot.+//!+//! Run with `cargo run -p moli-parkable-image --example park_unpark`.++use moli_disk_pool::DiskPool;+use moli_parkable_image::{ParkableImageManager, ParkableImagePolicy};++fn main() -> std::io::Result<()> {+ let pool = DiskPool::new(None)?;+ let manager = ParkableImageManager::new(Some(pool), ParkableImagePolicy::default());+ let image = manager.from_frozen_bytes(vec![42; 4096]);++ {+ let snapshot = image.snapshot()?;+ assert_eq!(snapshot[0], 42);+ // The image cannot discard its resident bytes while this snapshot exists.+ }++ manager.force_park_images();+ assert_eq!(manager.diagnostics().parked_count, 1);++ let snapshot = image.snapshot()?; // Synchronous unpark; keep the disk backup.+ assert_eq!(snapshot.len(), 4096);+ println!(+ "Restored {} bytes; resident images with a disk backup: {}.",+ snapshot.len(),+ manager.diagnostics().resident_with_disk_backup_count,+ );+ Ok(())+}diff --git a/moli-parkable-image/examples/reader_leases.rs b/moli-parkable-image/examples/reader_leases.rsnew file mode 100644index 000000000..997bcdb31--- /dev/null+++ b/moli-parkable-image/examples/reader_leases.rs@@ -0,0 +1,30 @@+//! Show that snapshots pin synthetic image bytes, but cloned image handles do not.+//!+//! Run with `cargo run -p moli-parkable-image --example reader_leases`.++use moli_disk_pool::DiskPool;+use moli_parkable_image::{ParkableImageManager, ParkableImagePolicy};++fn main() -> std::io::Result<()> {+ let manager =+ ParkableImageManager::new(Some(DiskPool::new(None)?), ParkableImagePolicy::default());+ let image = manager.from_frozen_bytes(vec![7; 4096]);+ let other_handle = image.clone();+ assert!(image.shares_storage_with(&other_handle));++ let first = image.snapshot()?;+ let second = first.clone();+ manager.force_park_images();+ assert_eq!(manager.diagnostics().parked_count, 0);++ drop(first);+ manager.force_park_images();+ assert_eq!(manager.diagnostics().parked_count, 0); // One reader remains.++ drop(second);+ manager.force_park_images();+ assert_eq!(manager.diagnostics().parked_count, 1);+ assert_eq!(other_handle.retained_memory_bytes(), 0);+ println!("Released both snapshot leases and parked the image with another handle still alive.");+ Ok(())+}diff --git a/moli-parkable-image/src/image.rs b/moli-parkable-image/src/image.rsnew file mode 100644index 000000000..663fc2cac--- /dev/null+++ b/moli-parkable-image/src/image.rs@@ -0,0 +1,506 @@+use std::{+ fmt, io,+ ops::Deref,+ sync::{Arc, Weak},+ time::{Duration, Instant},+};++use moli_disk_pool::{DiskData, DiskPool, ReservedChunk};+use parking_lot::Mutex;++use crate::manager::ParkableImageManager;++/// Encoded image bytes that can move between memory and one disk extent.+#[derive(Clone)]+pub struct ParkableImage {+ inner: Arc<ParkableImageInner>,+}++pub(crate) struct WeakParkableImage {+ inner: Weak<ParkableImageInner>,+}++struct ParkableImageInner {+ // Keep registration last: the storage (and any disk extent it owns) must+ // be dropped before unregistering wakes a capacity-waiting scheduler.+ state: Mutex<FrozenImageState>,+ registration: ParkableImageRegistration,+}++struct ParkableImageRegistration {+ id: u64,+ manager: ParkableImageManager,+}++struct FrozenImageState {+ storage: FrozenImageStorage,+ park_after: Instant,+ len: usize,+ reader_count: usize,+}++enum FrozenImageStorage {+ /// Encoded bytes are readable in memory. A disk backup, when present,+ /// makes the next park a memory-only state transition.+ Resident {+ bytes: Arc<Vec<u8>>,+ disk_backup: Option<Arc<DiskData>>,+ },+ /// The first disk write is running without holding the image mutex.+ Parking { bytes: Arc<Vec<u8>> },+ /// Resident bytes have been discarded; reads synchronously restore them.+ Parked { disk: Arc<DiskData> },+}++/// A read-only snapshot. While a snapshot exists, its image cannot discard the+/// corresponding in-memory bytes.+pub struct ParkableImageSnapshot {+ // Field order is intentional: Rust drops struct fields in declaration+ // order, so the encoded-byte reference is released before the lease can+ // make the image eligible for parking and wake the scheduler.+ data: Arc<Vec<u8>>,+ lease: SnapshotLease,+}++struct SnapshotLease {+ owner: WeakParkableImage,+}++enum ParkPreparation {+ Done(ParkOutcome),+ Write {+ pool: DiskPool,+ chunk: ReservedChunk,+ bytes: Arc<Vec<u8>>,+ },+}++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub(crate) enum ParkOutcome {+ Parked,+ AlreadyParked,+ BelowMinimum,+ Delayed { remaining: Duration },+ InUse,+ Unavailable,+}++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub(crate) enum ParkableImageStorageState {+ Resident,+ Parking,+ ResidentWithDiskBackup,+ Parked,+}++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub(crate) struct ParkableImageDiagnostics {+ pub len: usize,+ pub storage: ParkableImageStorageState,+ pub snapshot_count: usize,+ pub retained_memory_bytes: usize,+ pub retained_disk_bytes: usize,+}++impl Drop for ParkableImageRegistration {+ fn drop(&mut self) {+ self.manager.unregister(self.id);+ }+}++impl ParkableImage {+ pub(crate) fn new(manager: ParkableImageManager, id: u64, bytes: Vec<u8>) -> Self {+ let park_after = Instant::now()+ .checked_add(manager.policy().parking_delay)+ .expect("parkable image parking delay should fit Instant");+ Self {+ inner: Arc::new(ParkableImageInner {+ state: Mutex::new(FrozenImageState {+ len: bytes.len(),+ storage: FrozenImageStorage::Resident {+ bytes: Arc::new(bytes),+ disk_backup: None,+ },+ park_after,+ reader_count: 0,+ }),+ registration: ParkableImageRegistration { id, manager },+ }),+ }+ }++ pub fn len(&self) -> usize {+ self.inner.state.lock().len+ }++ pub fn is_empty(&self) -> bool {+ self.len() == 0+ }++ /// Memory retained by the encoded bytes, excluding the image handle.+ pub fn retained_memory_bytes(&self) -> usize {+ self.diagnostics().retained_memory_bytes+ }++ /// Returns whether two handles refer to the same encoded image backing.+ pub fn shares_storage_with(&self, other: &Self) -> bool {+ Arc::ptr_eq(&self.inner, &other.inner)+ }++ /// Returns a zero-copy read-only snapshot of resident bytes. A parked image+ /// is synchronously read back into memory first.+ pub fn snapshot(&self) -> io::Result<ParkableImageSnapshot> {+ let (snapshot, schedule_changed) = {+ let mut frozen = self.inner.state.lock();++ if let FrozenImageStorage::Parked { disk } = &frozen.storage {+ let disk = Arc::clone(disk);+ let data = disk.to_vec()?;+ debug_assert_eq!(data.len(), frozen.len);+ let bytes = Arc::new(data);+ frozen.storage = FrozenImageStorage::Resident {+ bytes: Arc::clone(&bytes),+ disk_backup: Some(disk),+ };+ self.manager().move_to_resident_while_image_locked(self);+ }+ let bytes = match &frozen.storage {+ FrozenImageStorage::Resident { bytes, .. }+ | FrozenImageStorage::Parking { bytes, .. } => Arc::clone(bytes),+ FrozenImageStorage::Parked { .. } => {+ unreachable!("parked storage should have been restored")+ }+ };+ let schedule_changed = frozen.reader_count == 0;+ frozen.reader_count = frozen+ .reader_count+ .checked_add(1)+ .expect("parkable image reader count should fit usize");+ (+ ParkableImageSnapshot {+ data: bytes,+ lease: SnapshotLease {+ owner: self.downgrade(),+ },+ },+ schedule_changed,+ )+ };+ if schedule_changed {+ self.manager().notify_schedule_changed();+ }+ Ok(snapshot)+ }++ pub fn read_range(&self, offset: usize, max_len: usize) -> io::Result<Vec<u8>> {+ let snapshot = self.snapshot()?;+ let Some(remaining) = snapshot.get(offset..) else {+ return Ok(Vec::new());+ };+ Ok(remaining[..remaining.len().min(max_len)].to_vec())+ }++ pub(crate) fn id(&self) -> u64 {+ self.inner.registration.id+ }++ fn manager(&self) -> &ParkableImageManager {+ &self.inner.registration.manager+ }++ fn retain_snapshot_reader(&self) {+ let mut frozen = self.inner.state.lock();+ frozen.reader_count = frozen+ .reader_count+ .checked_add(1)+ .expect("parkable image reader count should fit usize");+ }++ fn release_snapshot_reader(&self) {+ let reader_release_delay = self.manager().policy().reader_release_delay;+ let became_parkable = {+ let mut frozen = self.inner.state.lock();+ frozen.reader_count = frozen+ .reader_count+ .checked_sub(1)+ .expect("parkable image reader leases must remain balanced");+ if frozen.reader_count == 0 {+ frozen.park_after = Instant::now()+ .checked_add(reader_release_delay)+ .expect("parkable image reader release delay should fit Instant");+ true+ } else {+ false+ }+ };+ if became_parkable {+ self.manager().notify_schedule_changed();+ }+ }++ pub(crate) fn parking_deadline(&self) -> Option<Instant> {+ let frozen = self.inner.state.lock();+ let policy = self.manager().policy();+ if frozen.len < policy.min_size_to_park {+ return None;+ }+ let FrozenImageStorage::Resident { disk_backup, .. } = &frozen.storage else {+ return None;+ };+ if frozen.reader_count != 0 {+ return None;+ }+ if disk_backup.is_none()+ && !self+ .manager()+ .disk_pool()+ .is_some_and(|pool| pool.may_write())+ {+ return None;+ }+ Some(frozen.park_after)+ }++ /// Attempts to discard resident bytes according to the Blink parking+ /// policy. A successful first park writes exactly one disk extent.+ pub(crate) fn park(&self) -> io::Result<ParkOutcome> {+ self.park_impl(false)+ }++ /// Memory-pressure path: bypasses the time deadline, but never a live+ /// reader or another storage transition.+ pub(crate) fn force_park(&self) -> io::Result<ParkOutcome> {+ self.park_impl(true)+ }++ fn park_impl(&self, ignore_deadline: bool) -> io::Result<ParkOutcome> {+ match self.prepare_parking(ignore_deadline) {+ ParkPreparation::Done(outcome) => Ok(outcome),+ ParkPreparation::Write { pool, chunk, bytes } => {+ let write_result = pool.write(chunk, bytes.as_slice());+ self.complete_parking_write(write_result, bytes)+ }+ }+ }++ fn prepare_parking(&self, ignore_deadline: bool) -> ParkPreparation {+ let mut frozen = self.inner.state.lock();+ let policy = self.manager().policy();+ if frozen.len < policy.min_size_to_park {+ return ParkPreparation::Done(ParkOutcome::BelowMinimum);+ }+ match &frozen.storage {+ FrozenImageStorage::Resident { .. } => {}+ FrozenImageStorage::Parking { .. } => {+ return ParkPreparation::Done(ParkOutcome::InUse);+ }+ FrozenImageStorage::Parked { .. } => {+ return ParkPreparation::Done(ParkOutcome::AlreadyParked);+ }+ }+ if frozen.reader_count != 0 {+ return ParkPreparation::Done(ParkOutcome::InUse);+ }+ let now = Instant::now();+ if !ignore_deadline && now < frozen.park_after {+ return ParkPreparation::Done(ParkOutcome::Delayed {+ remaining: frozen.park_after.duration_since(now),+ });+ }++ let disk_backup = match &frozen.storage {+ FrozenImageStorage::Resident { disk_backup, .. } => disk_backup.clone(),+ FrozenImageStorage::Parking { .. } | FrozenImageStorage::Parked { .. } => {+ unreachable!("non-resident storage returned before parking eligibility")+ }+ };+ if let Some(disk) = disk_backup {+ frozen.storage = FrozenImageStorage::Parked { disk };+ self.manager().move_to_parked_while_image_locked(self);+ return ParkPreparation::Done(ParkOutcome::Parked);+ }++ let Some(pool) = self.manager().disk_pool() else {+ return ParkPreparation::Done(ParkOutcome::Unavailable);+ };+ let Some(chunk) = pool.try_reserve_chunk(frozen.len) else {+ return ParkPreparation::Done(ParkOutcome::Unavailable);+ };+ let bytes = match &frozen.storage {+ FrozenImageStorage::Resident { bytes, .. } => Arc::clone(bytes),+ FrozenImageStorage::Parking { .. } | FrozenImageStorage::Parked { .. } => {+ unreachable!("non-resident storage returned before starting a parking job")+ }+ };+ frozen.storage = FrozenImageStorage::Parking {+ bytes: Arc::clone(&bytes),+ };+ ParkPreparation::Write { pool, chunk, bytes }+ }++ fn complete_parking_write(+ &self,+ write_result: io::Result<DiskData>,+ write_bytes: Arc<Vec<u8>>,+ ) -> io::Result<ParkOutcome> {+ let mut frozen = self.inner.state.lock();+ if !matches!(frozen.storage, FrozenImageStorage::Parking { .. }) {+ return Err(io::Error::other(+ "parking write completed after its state was replaced",+ ));+ }++ match write_result {+ Ok(disk) if frozen.reader_count == 0 => {+ frozen.storage = FrozenImageStorage::Parked {+ disk: Arc::new(disk),+ };+ self.manager().move_to_parked_while_image_locked(self);+ Ok(ParkOutcome::Parked)+ }+ Ok(disk) => {+ frozen.storage = FrozenImageStorage::Resident {+ bytes: write_bytes,+ disk_backup: Some(Arc::new(disk)),+ };+ Ok(ParkOutcome::InUse)+ }+ Err(error) => {+ frozen.storage = FrozenImageStorage::Resident {+ bytes: write_bytes,+ disk_backup: None,+ };+ Err(error)+ }+ }+ }++ pub(crate) fn diagnostics(&self) -> ParkableImageDiagnostics {+ let frozen = self.inner.state.lock();+ let (storage, snapshot_count, retained_memory_bytes, retained_disk_bytes) =+ match &frozen.storage {+ FrozenImageStorage::Resident {+ bytes,+ disk_backup: None,+ } => (+ ParkableImageStorageState::Resident,+ frozen.reader_count,+ bytes.capacity(),+ 0,+ ),+ FrozenImageStorage::Resident {+ bytes,+ disk_backup: Some(disk),+ } => (+ ParkableImageStorageState::ResidentWithDiskBackup,+ frozen.reader_count,+ bytes.capacity(),+ disk.len(),+ ),+ FrozenImageStorage::Parking { bytes, .. } => (+ ParkableImageStorageState::Parking,+ frozen.reader_count,+ bytes.capacity(),+ 0,+ ),+ FrozenImageStorage::Parked { disk } => {+ (ParkableImageStorageState::Parked, 0, 0, disk.len())+ }+ };+ ParkableImageDiagnostics {+ len: frozen.len,+ storage,+ snapshot_count,+ retained_memory_bytes,+ retained_disk_bytes,+ }+ }++ pub(crate) fn downgrade(&self) -> WeakParkableImage {+ WeakParkableImage {+ inner: Arc::downgrade(&self.inner),+ }+ }+}++impl fmt::Debug for ParkableImage {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter+ .debug_struct("ParkableImage")+ .field("diagnostics", &self.diagnostics())+ .finish_non_exhaustive()+ }+}++impl WeakParkableImage {+ pub(crate) fn upgrade(&self) -> Option<ParkableImage> {+ self.inner.upgrade().map(|inner| ParkableImage { inner })+ }+}++impl Clone for WeakParkableImage {+ fn clone(&self) -> Self {+ Self {+ inner: self.inner.clone(),+ }+ }+}++impl fmt::Debug for WeakParkableImage {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter+ .debug_struct("WeakParkableImage")+ .field("live", &(self.inner.strong_count() != 0))+ .finish()+ }+}++impl Deref for ParkableImageSnapshot {+ type Target = [u8];++ fn deref(&self) -> &Self::Target {+ self.data.as_slice()+ }+}++impl Clone for ParkableImageSnapshot {+ fn clone(&self) -> Self {+ let data = Arc::clone(&self.data);+ let lease = self.lease.clone();+ Self { data, lease }+ }+}++impl Clone for SnapshotLease {+ fn clone(&self) -> Self {+ if let Some(image) = self.owner.upgrade() {+ image.retain_snapshot_reader();+ }+ Self {+ owner: self.owner.clone(),+ }+ }+}++impl Drop for SnapshotLease {+ fn drop(&mut self) {+ if let Some(image) = self.owner.upgrade() {+ image.release_snapshot_reader();+ }+ }+}++impl AsRef<[u8]> for ParkableImageSnapshot {+ fn as_ref(&self) -> &[u8] {+ self+ }+}++impl fmt::Debug for ParkableImageSnapshot {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter+ .debug_struct("ParkableImageSnapshot")+ .field("len", &self.data.len())+ .finish_non_exhaustive()+ }+}diff --git a/moli-parkable-image/src/lib.rs b/moli-parkable-image/src/lib.rsnew file mode 100644index 000000000..2d19f06ef--- /dev/null+++ b/moli-parkable-image/src/lib.rs@@ -0,0 +1,20 @@+//! Parkable encoded image storage.+//!+//! Completed encoded images are decoded through read-only snapshots and may be+//! parked into one `DiskPool` extent. Reading a parked image unparks it+//! synchronously; the retained disk extent lets a later park discard memory+//! without another write. The manager keeps resident and parked registries+//! separate, owns parking sweeps, and exposes the next resident deadline to+//! its runtime. Reader release uses a short grace period before re-parking.++mod image;+mod manager;+mod policy;+mod registry;++pub use image::{ParkableImage, ParkableImageSnapshot};+pub use manager::{ParkableImageManager, ParkableImageManagerDiagnostics};+pub use policy::ParkableImagePolicy;++#[cfg(test)]+mod tests;diff --git a/moli-parkable-image/src/manager.rs b/moli-parkable-image/src/manager.rsnew file mode 100644index 000000000..16c555586--- /dev/null+++ b/moli-parkable-image/src/manager.rs@@ -0,0 +1,307 @@+use std::{+ fmt,+ sync::{+ Arc,+ atomic::{AtomicU64, Ordering},+ },+ time::Instant,+};++use moli_disk_pool::DiskPool;+use parking_lot::Mutex;++use crate::{+ image::{ParkOutcome, ParkableImage, ParkableImageStorageState},+ policy::ParkableImagePolicy,+ registry::ParkableImageRegistry,+};++/// Browser-runtime scoped owner and deadline scheduler for parkable images.+#[derive(Clone)]+pub struct ParkableImageManager {+ inner: Arc<ParkableImageManagerInner>,+}++struct ParkableImageManagerInner {+ disk_pool: Option<DiskPool>,+ policy: ParkableImagePolicy,+ next_image_id: AtomicU64,+ registry: Mutex<ParkableImageRegistry>,+ // Suppress expired deadlines after a capacity miss. Arm before scanning;+ // notifications clear this flag, and an unavailable sweep leaves it+ // untouched so it cannot overwrite a concurrent wakeup.+ // Never hold this lock while scanning, doing I/O, or invoking callbacks.+ waiting_for_change: Mutex<bool>,+ schedule_wakeup: Option<ScheduleWakeup>,+}++type ScheduleWakeup = Arc<dyn Fn() + Send + Sync + 'static>;++#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]+pub struct ParkableImageManagerDiagnostics {+ pub image_count: usize,+ pub resident_count: usize,+ pub parking_count: usize,+ pub resident_with_disk_backup_count: usize,+ pub parked_count: usize,+ pub retained_memory_bytes: usize,+ pub retained_disk_bytes: usize,+}++#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]+pub(crate) struct ParkableImageSweepReport {+ pub considered: usize,+ pub parked: usize,+ pub already_parked: usize,+ pub delayed: usize,+ pub in_use: usize,+ pub ineligible: usize,+ pub unavailable: usize,+ pub write_failures: usize,+}++impl ParkableImageManager {+ pub fn new(disk_pool: Option<DiskPool>, policy: ParkableImagePolicy) -> Self {+ Self::build(disk_pool, policy, None)+ }++ /// Creates a manager whose owner is notified whenever its next parking+ /// deadline may have changed. The callback should only wake the owner's+ /// scheduler; parking work itself remains outside the callback.+ pub fn new_with_schedule_wakeup(+ disk_pool: Option<DiskPool>,+ policy: ParkableImagePolicy,+ wakeup: impl Fn() + Send + Sync + 'static,+ ) -> Self {+ Self::build(disk_pool, policy, Some(Arc::new(wakeup)))+ }++ fn build(+ disk_pool: Option<DiskPool>,+ policy: ParkableImagePolicy,+ schedule_wakeup: Option<ScheduleWakeup>,+ ) -> Self {+ Self {+ inner: Arc::new(ParkableImageManagerInner {+ disk_pool,+ policy,+ next_image_id: AtomicU64::new(0),+ registry: Mutex::new(ParkableImageRegistry::default()),+ waiting_for_change: Mutex::new(false),+ schedule_wakeup,+ }),+ }+ }++ pub(crate) fn policy(&self) -> ParkableImagePolicy {+ self.inner.policy+ }++ pub fn from_frozen_bytes(&self, bytes: Vec<u8>) -> ParkableImage {+ let should_register = bytes.len() >= self.inner.policy.min_size_to_park;+ let image = ParkableImage::new(self.clone(), self.allocate_image_id(), bytes);+ if should_register {+ self.register_resident(&image);+ }+ image+ }++ /// Returns the earliest deadline among schedulable resident images.+ /// Parked images are kept in a separate registry and are not inspected.+ /// A sweep in progress or waiting for a change can suppress the deadline.+ pub fn next_parking_deadline(&self) -> Option<Instant> {+ if *self.inner.waiting_for_change.lock() {+ return None;+ }+ self.resident_images()+ .into_iter()+ .filter_map(|image| image.parking_deadline())+ .min()+ }++ /// Attempts to park resident images whose deadline has elapsed.+ ///+ /// This does not wait for future deadlines. Disk I/O is synchronous; the+ /// owner should wait for [`Self::next_parking_deadline`] and call this from+ /// a blocking worker.+ pub fn park_images(&self) {+ self.park_images_with_report();+ }++ pub(crate) fn park_images_with_report(&self) -> ParkableImageSweepReport {+ if !self.begin_scheduled_sweep() {+ return ParkableImageSweepReport::default();+ }+ let now = Instant::now();+ let due = self+ .resident_images()+ .into_iter()+ .filter(|image| {+ image+ .parking_deadline()+ .is_some_and(|deadline| deadline <= now)+ })+ .collect();+ let report = self.sweep(due, ParkableImage::park);+ self.finish_sweep(report);+ report+ }++ /// Attempts to park all resident images, ignoring deadlines and retrying+ /// after unavailable disk reservations.+ ///+ /// Live readers, in-flight writes, size thresholds, and pool limits still+ /// apply. Disk I/O is synchronous. Normal scheduling uses [`Self::park_images`].+ pub fn force_park_images(&self) {+ self.force_park_images_with_report();+ }++ pub(crate) fn force_park_images_with_report(&self) -> ParkableImageSweepReport {+ self.begin_forced_sweep();+ let images = self.resident_images();+ let report = self.sweep(images, ParkableImage::force_park);+ self.finish_sweep(report);+ report+ }++ pub fn diagnostics(&self) -> ParkableImageManagerDiagnostics {+ let images = self.inner.registry.lock().all_images();+ let mut diagnostics = ParkableImageManagerDiagnostics::default();+ for image in images {+ let image = image.diagnostics();+ diagnostics.image_count += 1;+ match image.storage {+ ParkableImageStorageState::Resident => diagnostics.resident_count += 1,+ ParkableImageStorageState::Parking => diagnostics.parking_count += 1,+ ParkableImageStorageState::ResidentWithDiskBackup => {+ diagnostics.resident_with_disk_backup_count += 1;+ }+ ParkableImageStorageState::Parked => diagnostics.parked_count += 1,+ }+ diagnostics.retained_memory_bytes = diagnostics+ .retained_memory_bytes+ .saturating_add(image.retained_memory_bytes);+ diagnostics.retained_disk_bytes = diagnostics+ .retained_disk_bytes+ .saturating_add(image.retained_disk_bytes);+ }+ diagnostics+ }++ pub(crate) fn disk_pool(&self) -> Option<DiskPool> {+ self.inner.disk_pool.clone()+ }++ pub(crate) fn notify_schedule_changed(&self) {+ *self.inner.waiting_for_change.lock() = false;+ self.wake_scheduler();+ }++ /// Moves an image between the physical-residency indexes.+ ///+ /// The caller must hold the image state lock. The manager never acquires+ /// an image lock while holding the registry lock, so the global lock order+ /// is always image state -> manager registry.+ pub(crate) fn move_to_parked_while_image_locked(&self, image: &ParkableImage) {+ self.inner.registry.lock().move_to_parked(image);+ }++ /// See [`Self::move_to_parked_while_image_locked`] for the lock-order+ /// contract.+ pub(crate) fn move_to_resident_while_image_locked(&self, image: &ParkableImage) {+ self.inner.registry.lock().move_to_resident(image);+ }++ pub(crate) fn unregister(&self, id: u64) {+ let removed = self.inner.registry.lock().remove(id);+ if removed {+ self.notify_schedule_changed();+ }+ }++ fn allocate_image_id(&self) -> u64 {+ self.inner+ .next_image_id+ .fetch_add(1, Ordering::Relaxed)+ .saturating_add(1)+ }++ fn register_resident(&self, image: &ParkableImage) {+ self.inner.registry.lock().register_resident(image);+ self.notify_schedule_changed();+ }++ fn resident_images(&self) -> Vec<ParkableImage> {+ self.inner.registry.lock().resident_images()+ }++ fn begin_scheduled_sweep(&self) -> bool {+ let mut waiting = self.inner.waiting_for_change.lock();+ if *waiting {+ return false;+ }+ *waiting = true;+ true+ }++ fn begin_forced_sweep(&self) {+ *self.inner.waiting_for_change.lock() = true;+ }++ fn finish_sweep(&self, report: ParkableImageSweepReport) {+ // Overlapping completions may allow an extra retry; they must never+ // re-arm the wait after a notification has cleared it.+ if report.unavailable == 0 {+ *self.inner.waiting_for_change.lock() = false;+ }+ self.wake_scheduler();+ }++ fn wake_scheduler(&self) {+ if let Some(wakeup) = &self.inner.schedule_wakeup {+ wakeup();+ }+ }++ fn sweep(+ &self,+ images: Vec<ParkableImage>,+ park: fn(&ParkableImage) -> std::io::Result<ParkOutcome>,+ ) -> ParkableImageSweepReport {+ let mut report = ParkableImageSweepReport::default();+ for image in images {+ report.considered += 1;+ match park(&image) {+ Ok(ParkOutcome::Parked) => report.parked += 1,+ Ok(ParkOutcome::AlreadyParked) => report.already_parked += 1,+ Ok(ParkOutcome::Delayed { .. }) => report.delayed += 1,+ Ok(ParkOutcome::InUse) => report.in_use += 1,+ Ok(ParkOutcome::Unavailable) => report.unavailable += 1,+ Ok(ParkOutcome::BelowMinimum) => {+ report.ineligible += 1;+ }+ Err(_) => report.write_failures += 1,+ }+ }+ report+ }+}++impl Default for ParkableImageManager {+ fn default() -> Self {+ Self::new(None, ParkableImagePolicy::default())+ }+}++impl fmt::Debug for ParkableImageManager {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ formatter+ .debug_struct("ParkableImageManager")+ .field("policy", &self.policy())+ .field("diagnostics", &self.diagnostics())+ .finish_non_exhaustive()+ }+}++#[cfg(test)]+mod tests;diff --git a/moli-parkable-image/src/manager/tests.rs b/moli-parkable-image/src/manager/tests.rsnew file mode 100644index 000000000..58b305018--- /dev/null+++ b/moli-parkable-image/src/manager/tests.rs@@ -0,0 +1,513 @@+use std::{+ sync::{+ Arc, Barrier, OnceLock, Weak,+ atomic::{AtomicUsize, Ordering},+ mpsc,+ },+ thread,+ time::{Duration, Instant},+};++use moli_disk_pool::DiskPool;++use super::{ParkableImageManager, ParkableImageManagerInner, ParkableImageSweepReport};+use crate::{+ ParkableImagePolicy,+ image::{ParkOutcome, ParkableImage, ParkableImageStorageState},+};++fn immediate_policy() -> ParkableImagePolicy {+ ParkableImagePolicy {+ min_size_to_park: 1,+ parking_delay: Duration::ZERO,+ reader_release_delay: Duration::ZERO,+ }+}++fn manager(capacity: Option<u64>) -> (DiskPool, ParkableImageManager) {+ let pool = DiskPool::new(capacity).unwrap();+ let manager = ParkableImageManager::new(Some(pool.clone()), immediate_policy());+ (pool, manager)+}++fn unavailable_report() -> ParkableImageSweepReport {+ ParkableImageSweepReport {+ considered: 1,+ unavailable: 1,+ ..ParkableImageSweepReport::default()+ }+}++fn assert_completes(operation: impl FnOnce() + Send + 'static) {+ let (sender, receiver) = mpsc::channel();+ let worker = thread::spawn(move || {+ operation();+ let _ = sender.send(());+ });+ assert_ne!(+ receiver.recv_timeout(Duration::from_secs(30)),+ Err(mpsc::RecvTimeoutError::Timeout),+ "parking or a notification callback deadlocked"+ );+ worker.join().unwrap();+}++#[test]+fn scheduled_sweep_arms_wait_before_scanning() {+ let (_, manager) = manager(None);+ let image = manager.from_frozen_bytes(vec![1; 4]);+ assert!(manager.next_parking_deadline().is_some());++ assert!(manager.begin_scheduled_sweep());+ assert!(manager.next_parking_deadline().is_none());+ assert!(!manager.begin_scheduled_sweep());++ let report = manager.sweep(vec![image.clone()], ParkableImage::park);+ assert_eq!(report.parked, 1);+ manager.finish_sweep(report);+ assert!(manager.begin_scheduled_sweep());+ manager.finish_sweep(ParkableImageSweepReport::default());+}++#[test]+fn notification_before_sweep_does_not_hide_a_later_capacity_miss() {+ let manager = ParkableImageManager::default();+ manager.notify_schedule_changed();+ assert!(manager.begin_scheduled_sweep());+ manager.finish_sweep(unavailable_report());+ assert!(!manager.begin_scheduled_sweep());+}++#[test]+fn notification_during_unavailable_sweep_survives_completion() {+ for notifications in [1, 32] {+ let manager = ParkableImageManager::default();+ assert!(manager.begin_scheduled_sweep());+ for _ in 0..notifications {+ manager.notify_schedule_changed();+ }+ manager.finish_sweep(unavailable_report());+ assert!(manager.begin_scheduled_sweep());++ // The notification permits a retry, not unlimited failed sweeps.+ manager.finish_sweep(unavailable_report());+ assert!(!manager.begin_scheduled_sweep());+ }+}++#[test]+fn notification_after_unavailable_sweep_allows_retry() {+ let manager = ParkableImageManager::default();+ assert!(manager.begin_scheduled_sweep());+ manager.finish_sweep(unavailable_report());+ assert!(!manager.begin_scheduled_sweep());+ manager.notify_schedule_changed();+ assert!(manager.begin_scheduled_sweep());+ manager.finish_sweep(ParkableImageSweepReport::default());+}++#[test]+fn only_unavailable_outcomes_keep_a_sweep_waiting_for_change() {+ let reports = [+ ParkableImageSweepReport::default(),+ ParkableImageSweepReport {+ considered: 1,+ parked: 1,+ ..ParkableImageSweepReport::default()+ },+ ParkableImageSweepReport {+ considered: 1,+ already_parked: 1,+ ..ParkableImageSweepReport::default()+ },+ ParkableImageSweepReport {+ considered: 1,+ delayed: 1,+ ..ParkableImageSweepReport::default()+ },+ ParkableImageSweepReport {+ considered: 1,+ in_use: 1,+ ..ParkableImageSweepReport::default()+ },+ ParkableImageSweepReport {+ considered: 1,+ ineligible: 1,+ ..ParkableImageSweepReport::default()+ },+ ParkableImageSweepReport {+ considered: 1,+ write_failures: 1,+ ..ParkableImageSweepReport::default()+ },+ ];+ for report in reports {+ let manager = ParkableImageManager::default();+ assert!(manager.begin_scheduled_sweep());+ manager.finish_sweep(report);+ assert!(!*manager.inner.waiting_for_change.lock(), "{report:?}");++ assert!(manager.begin_scheduled_sweep());+ manager.finish_sweep(ParkableImageSweepReport {+ considered: report.considered + 1,+ unavailable: 1,+ ..report+ });+ assert!(!manager.begin_scheduled_sweep(), "{report:?}");+ }+}++#[test]+fn empty_and_future_deadline_sweeps_do_not_stay_waiting() {+ let pool = DiskPool::new(None).unwrap();+ let manager = ParkableImageManager::new(+ Some(pool),+ ParkableImagePolicy {+ parking_delay: Duration::from_secs(3600),+ ..immediate_policy()+ },+ );+ manager.park_images();+ assert!(!*manager.inner.waiting_for_change.lock());++ let image = manager.from_frozen_bytes(vec![1; 4]);+ let deadline = manager.next_parking_deadline().unwrap();+ assert!(deadline > Instant::now());+ for _ in 0..3 {+ assert_eq!(manager.park_images_with_report().considered, 0);+ assert_eq!(manager.next_parking_deadline(), Some(deadline));+ }+ assert_eq!(manager.force_park_images_with_report().parked, 1);+ assert_eq!(image.retained_memory_bytes(), 0);+ assert!(!*manager.inner.waiting_for_change.lock());+}++#[test]+fn failed_write_does_not_leave_the_sweep_in_progress() {+ let (pool, manager) = manager(None);+ let image = manager.from_frozen_bytes(vec![1; 4]);+ pool.fail_next_write_for_test();++ let report = manager.park_images_with_report();+ assert_eq!(report.write_failures, 1);+ assert!(!*manager.inner.waiting_for_change.lock());+ assert_eq!(manager.next_parking_deadline(), None);+ assert_eq!(manager.park_images_with_report().considered, 0);+ assert_eq!(image.snapshot().unwrap().as_ref(), &[1; 4]);+}++#[test]+fn registering_an_image_during_a_failed_sweep_preserves_its_retry() {+ let (_, manager) = manager(Some(4));+ let oversized = manager.from_frozen_bytes(vec![1; 8]);+ assert!(manager.begin_scheduled_sweep());+ let report = manager.sweep(vec![oversized.clone()], ParkableImage::park);+ assert_eq!(report, unavailable_report());++ let small = manager.from_frozen_bytes(vec![2; 4]);+ manager.finish_sweep(report);++ assert!(manager.next_parking_deadline().is_some());+ let retry = manager.park_images_with_report();+ assert_eq!(retry.considered, 2);+ assert_eq!(retry.parked, 1);+ assert_eq!(retry.unavailable, 1);+ assert_eq!(small.retained_memory_bytes(), 0);+ assert_eq!(oversized.retained_memory_bytes(), 8);+ assert_eq!(manager.next_parking_deadline(), None);+}++#[test]+fn last_reader_release_during_a_failed_sweep_preserves_its_retry() {+ assert_completes(|| {+ let (_, manager) = manager(Some(4));+ let oversized = manager.from_frozen_bytes(vec![1; 8]);+ let small = manager.from_frozen_bytes(vec![2; 4]);+ let first = small.snapshot().unwrap();+ let last = first.clone();+ assert!(manager.begin_scheduled_sweep());+ let report = manager.sweep(vec![oversized.clone()], ParkableImage::park);+ assert_eq!(report, unavailable_report());++ drop(first);+ assert!(*manager.inner.waiting_for_change.lock());+ thread::spawn(move || drop(last)).join().unwrap();+ manager.finish_sweep(report);++ let retry = manager.park_images_with_report();+ assert_eq!(retry.parked, 1);+ assert_eq!(retry.unavailable, 1);+ assert_eq!(small.retained_memory_bytes(), 0);+ assert_eq!(oversized.retained_memory_bytes(), 8);+ });+}++#[test]+fn acquiring_a_reader_during_a_failed_sweep_preserves_the_notification() {+ let (_, manager) = manager(Some(4));+ let oversized = manager.from_frozen_bytes(vec![1; 8]);+ assert!(manager.begin_scheduled_sweep());+ let report = manager.sweep(vec![oversized.clone()], ParkableImage::park);+ assert_eq!(report, unavailable_report());++ let snapshot = oversized.snapshot().unwrap();+ manager.finish_sweep(report);+ assert!(!*manager.inner.waiting_for_change.lock());+ assert_eq!(manager.park_images_with_report().considered, 0);++ drop(snapshot);+ assert!(manager.next_parking_deadline().is_some());+ assert_eq!(manager.park_images_with_report(), unavailable_report());+}++#[test]+fn releasing_an_extent_before_or_after_failed_completion_allows_retry() {+ assert_completes(|| {+ for release_before_completion in [true, false] {+ let (pool, manager) = manager(Some(4));+ let owner = manager.from_frozen_bytes(vec![1; 4]);+ assert_eq!(owner.park().unwrap(), ParkOutcome::Parked);+ let waiting = manager.from_frozen_bytes(vec![2; 4]);+ assert!(manager.begin_scheduled_sweep());+ let report = manager.sweep(vec![waiting.clone()], ParkableImage::park);+ assert_eq!(report, unavailable_report());++ if !release_before_completion {+ manager.finish_sweep(report);+ assert_eq!(manager.next_parking_deadline(), None);+ }+ thread::spawn(move || drop(owner)).join().unwrap();+ assert_eq!(pool.diagnostics().free_bytes, 4);+ if release_before_completion {+ manager.finish_sweep(report);+ }++ assert!(manager.next_parking_deadline().is_some());+ assert_eq!(manager.park_images_with_report().parked, 1);+ assert_eq!(waiting.snapshot().unwrap().as_ref(), &[2; 4]);+ }+ });+}++#[test]+fn force_retries_after_an_external_pool_owner_releases_capacity() {+ let (pool, manager) = manager(Some(4));+ let external = pool.store(&[1; 4]).unwrap().unwrap();+ let image = manager.from_frozen_bytes(vec![2; 4]);+ assert_eq!(manager.park_images_with_report(), unavailable_report());++ // A generic DiskData owner does not send image-manager notifications.+ drop(external);+ assert_eq!(pool.diagnostics().free_bytes, 4);+ assert_eq!(manager.park_images_with_report().considered, 0);++ assert_eq!(manager.force_park_images_with_report().parked, 1);+ assert!(!*manager.inner.waiting_for_change.lock());+ assert_eq!(image.retained_memory_bytes(), 0);+ assert_eq!(image.snapshot().unwrap().as_ref(), &[2; 4]);+}++#[test]+fn last_temporary_image_drop_inside_a_sweep_cannot_deadlock_or_lose_its_wakeup() {+ assert_completes(|| {+ for len in [4, 8] {+ let (pool, manager) = manager(Some(4));+ let image = manager.from_frozen_bytes(vec![1; len]);+ let images = manager.resident_images();+ drop(image);++ assert!(manager.begin_scheduled_sweep());+ // Consuming the only remaining handle unregisters the image and+ // notifies this same manager from within the sweep.+ let report = manager.sweep(images, ParkableImage::park);+ assert_eq!(report.parked, usize::from(len == 4));+ assert_eq!(report.unavailable, usize::from(len == 8));+ manager.finish_sweep(report);++ assert!(!*manager.inner.waiting_for_change.lock());+ assert_eq!(manager.diagnostics().image_count, 0);+ let disk = pool.diagnostics();+ assert_eq!(disk.disk_footprint_bytes, disk.free_bytes as u64);+ }+ });+}++#[test]+fn wakeup_callbacks_can_query_the_manager_without_holding_its_locks() {+ assert_completes(|| {+ let owner = Arc::new(OnceLock::<Weak<ParkableImageManagerInner>>::new());+ let callback_owner = Arc::clone(&owner);+ let wakeups = Arc::new(AtomicUsize::new(0));+ let callback_wakeups = Arc::clone(&wakeups);+ let manager = ParkableImageManager::new_with_schedule_wakeup(+ Some(DiskPool::new(None).unwrap()),+ immediate_policy(),+ move || {+ let inner = callback_owner.get().unwrap().upgrade().unwrap();+ assert!(inner.waiting_for_change.try_lock().is_some());+ assert!(inner.registry.try_lock().is_some());+ let manager = ParkableImageManager { inner };+ manager.next_parking_deadline();+ manager.diagnostics();+ callback_wakeups.fetch_add(1, Ordering::Relaxed);+ },+ );+ owner.set(Arc::downgrade(&manager.inner)).unwrap();++ let image = manager.from_frozen_bytes(vec![1; 4]);+ let snapshot = image.snapshot().unwrap();+ drop(snapshot);+ manager.park_images();+ drop(image);+ assert_eq!(wakeups.load(Ordering::Relaxed), 5);+ });+}++#[test]+fn overlapping_sweeps_preserve_notifications_in_every_event_order() {+ #[derive(Clone, Copy, Debug)]+ enum Event {+ Begin(usize),+ Finish(usize),+ Notify,+ }+ use Event::{Begin, Finish, Notify};++ // All six interleavings that preserve each sweep's begin-before-finish.+ let orders = [+ [Begin(0), Finish(0), Begin(1), Finish(1)],+ [Begin(0), Begin(1), Finish(0), Finish(1)],+ [Begin(0), Begin(1), Finish(1), Finish(0)],+ [Begin(1), Finish(1), Begin(0), Finish(0)],+ [Begin(1), Begin(0), Finish(1), Finish(0)],+ [Begin(1), Begin(0), Finish(0), Finish(1)],+ ];+ let mut scenarios = 0;+ for order in orders {+ for notification_at in 0..=order.len() {+ let mut events = order.to_vec();+ events.insert(notification_at, Notify);+ for forced in [[false, false], [false, true], [true, false], [true, true]] {+ for unavailable in [[false, false], [false, true], [true, false], [true, true]] {+ let manager = ParkableImageManager::default();+ let mut admitted = [false; 2];+ let mut last_begin = 0;+ for (step, event) in events.iter().enumerate() {+ match *event {+ Begin(id) => {+ admitted[id] = if forced[id] {+ manager.begin_forced_sweep();+ true+ } else {+ manager.begin_scheduled_sweep()+ };+ if admitted[id] {+ last_begin = step;+ }+ }+ Finish(id) if admitted[id] => {+ manager.finish_sweep(if unavailable[id] {+ unavailable_report()+ } else {+ ParkableImageSweepReport::default()+ });+ }+ Finish(_) => {}+ Notify => manager.notify_schedule_changed(),+ }+ }+ let waiting = *manager.inner.waiting_for_change.lock();+ let missed_capacity = (0..2).any(|id| admitted[id] && unavailable[id]);+ if notification_at > last_begin || !missed_capacity {+ assert!(+ !waiting,+ "lost wakeup: {events:?}, forced={forced:?}, unavailable={unavailable:?}"+ );+ } else if (0..2).all(|id| !admitted[id] || unavailable[id]) {+ assert!(+ waiting,+ "capacity misses must wait: {events:?}, forced={forced:?}"+ );+ }+ scenarios += 1;+ }+ }+ }+ }+ assert_eq!(scenarios, 480);+}++#[test]+fn concurrent_normal_force_read_and_drop_operations_preserve_data_and_progress() {+ assert_completes(|| {+ const IMAGE_COUNT: usize = 8;+ const IMAGE_SIZE: usize = 4096;+ const ROUNDS: usize = 256;+ let (pool, manager) = manager(None);+ let images = (0..IMAGE_COUNT)+ .map(|id| manager.from_frozen_bytes(vec![id as u8; IMAGE_SIZE]))+ .collect::<Vec<_>>();+ let start = Arc::new(Barrier::new(4));+ let workers = (0..4)+ .map(|role| {+ let manager = manager.clone();+ let images = images.clone();+ let start = Arc::clone(&start);+ thread::spawn(move || {+ start.wait();+ for round in 0..ROUNDS {+ match role {+ 0 => manager.park_images(),+ 1 => manager.force_park_images(),+ 2 => {+ let id = round % IMAGE_COUNT;+ let snapshot = images[id].snapshot().unwrap();+ let clone = snapshot.clone();+ drop(snapshot);+ assert_eq!(clone.as_ref(), &[id as u8; IMAGE_SIZE]);+ }+ 3 => {+ let image = manager.from_frozen_bytes(vec![9; IMAGE_SIZE]);+ let snapshot = image.snapshot().unwrap();+ drop(image);+ assert_eq!(snapshot.as_ref(), &[9; IMAGE_SIZE]);+ }+ _ => unreachable!(),+ }+ thread::yield_now();+ }+ })+ })+ .collect::<Vec<_>>();+ for worker in workers {+ worker.join().unwrap();+ }++ for (id, image) in images.iter().enumerate() {+ assert_eq!(image.snapshot().unwrap().as_ref(), &[id as u8; IMAGE_SIZE]);+ }+ // Ordinary scheduling must still progress after concurrent activity.+ assert_eq!(manager.park_images_with_report().parked, IMAGE_COUNT);+ let diagnostics = manager.diagnostics();+ assert_eq!(diagnostics.image_count, IMAGE_COUNT);+ assert_eq!(diagnostics.parked_count, IMAGE_COUNT);+ assert_eq!(diagnostics.retained_memory_bytes, 0);+ assert_eq!(diagnostics.retained_disk_bytes, IMAGE_COUNT * IMAGE_SIZE);+ assert!(!*manager.inner.waiting_for_change.lock());+ for image in &images {+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Parked+ );+ }+ let disk = pool.diagnostics();+ assert_eq!(+ disk.disk_footprint_bytes - disk.free_bytes as u64,+ (IMAGE_COUNT * IMAGE_SIZE) as u64+ );+ drop(images);+ assert_eq!(manager.diagnostics().image_count, 0);+ let disk = pool.diagnostics();+ assert_eq!(disk.disk_footprint_bytes, disk.free_bytes as u64);+ });+}diff --git a/moli-parkable-image/src/policy.rs b/moli-parkable-image/src/policy.rsnew file mode 100644index 000000000..94589ca13--- /dev/null+++ b/moli-parkable-image/src/policy.rs@@ -0,0 +1,24 @@+use std::time::Duration;++const DEFAULT_MIN_SIZE_TO_PARK: usize = 1024;+const DEFAULT_PARKING_DELAY: Duration = Duration::from_secs(30);+const DEFAULT_READER_RELEASE_DELAY: Duration = Duration::from_secs(2);++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub struct ParkableImagePolicy {+ pub min_size_to_park: usize,+ /// How long an unused frozen image remains resident.+ pub parking_delay: Duration,+ /// Grace period after the last reader releases the encoded bytes.+ pub reader_release_delay: Duration,+}++impl Default for ParkableImagePolicy {+ fn default() -> Self {+ Self {+ min_size_to_park: DEFAULT_MIN_SIZE_TO_PARK,+ parking_delay: DEFAULT_PARKING_DELAY,+ reader_release_delay: DEFAULT_READER_RELEASE_DELAY,+ }+ }+}diff --git a/moli-parkable-image/src/registry.rs b/moli-parkable-image/src/registry.rsnew file mode 100644index 000000000..0c6db33c5--- /dev/null+++ b/moli-parkable-image/src/registry.rs@@ -0,0 +1,52 @@+use std::collections::HashMap;++use crate::image::{ParkableImage, WeakParkableImage};++#[derive(Default)]+pub(crate) struct ParkableImageRegistry {+ resident: HashMap<u64, WeakParkableImage>,+ parked: HashMap<u64, WeakParkableImage>,+}++impl ParkableImageRegistry {+ pub(crate) fn register_resident(&mut self, image: &ParkableImage) {+ let id = image.id();+ debug_assert!(!self.parked.contains_key(&id));+ let previous = self.resident.insert(id, image.downgrade());+ debug_assert!(previous.is_none());+ }++ pub(crate) fn move_to_parked(&mut self, image: &ParkableImage) {+ let id = image.id();+ let resident = self.resident.remove(&id);+ debug_assert!(resident.is_some());+ let previous = self.parked.insert(id, image.downgrade());+ debug_assert!(previous.is_none());+ }++ pub(crate) fn move_to_resident(&mut self, image: &ParkableImage) {+ let id = image.id();+ let parked = self.parked.remove(&id);+ debug_assert!(parked.is_some());+ let previous = self.resident.insert(id, image.downgrade());+ debug_assert!(previous.is_none());+ }++ pub(crate) fn remove(&mut self, id: u64) -> bool {+ self.resident.remove(&id).is_some() || self.parked.remove(&id).is_some()+ }++ pub(crate) fn resident_images(&self) -> Vec<ParkableImage> {+ self.resident+ .values()+ .filter_map(WeakParkableImage::upgrade)+ .collect()+ }++ pub(crate) fn all_images(&self) -> Vec<ParkableImage> {+ let mut images = self.resident_images();+ images.reserve(self.parked.len());+ images.extend(self.parked.values().filter_map(WeakParkableImage::upgrade));+ images+ }+}diff --git a/moli-parkable-image/src/tests.rs b/moli-parkable-image/src/tests.rsnew file mode 100644index 000000000..389b9787b--- /dev/null+++ b/moli-parkable-image/src/tests.rs@@ -0,0 +1,653 @@+use std::{+ sync::{+ Arc,+ atomic::{AtomicBool, AtomicUsize, Ordering},+ },+ time::{Duration, Instant},+};++use moli_disk_pool::DiskPool;+use parking_lot::Mutex;++use crate::{+ ParkableImageManager, ParkableImagePolicy,+ image::{ParkOutcome, ParkableImageStorageState},+};++fn manager(policy: ParkableImagePolicy) -> (DiskPool, ParkableImageManager) {+ let pool = DiskPool::new(None).unwrap();+ let manager = ParkableImageManager::new(Some(pool.clone()), policy);+ (pool, manager)+}++fn immediate_policy() -> ParkableImagePolicy {+ ParkableImagePolicy {+ min_size_to_park: 1,+ parking_delay: Duration::ZERO,+ reader_release_delay: Duration::ZERO,+ }+}++fn reference_bytes(len: usize) -> Vec<u8> {+ (0..len)+ .map(|offset| u8::try_from((offset * 37) % 251).unwrap())+ .collect()+}++#[test]+fn default_policy_keeps_unused_and_recently_read_images_resident() {+ let policy = ParkableImagePolicy::default();+ assert_eq!(policy.min_size_to_park, 1024);+ assert_eq!(policy.parking_delay, Duration::from_secs(30));+ assert_eq!(policy.reader_release_delay, Duration::from_secs(2));+}++#[test]+fn unused_image_observes_delay_but_used_image_can_park_immediately() {+ let (_, manager) = manager(ParkableImagePolicy {+ min_size_to_park: 1,+ parking_delay: Duration::from_secs(30),+ reader_release_delay: Duration::ZERO,+ });+ let image = manager.from_frozen_bytes(vec![7; 128]);+ assert!(matches!(image.park().unwrap(), ParkOutcome::Delayed { .. }));++ let snapshot = image.snapshot().unwrap();+ assert_eq!(image.park().unwrap(), ParkOutcome::InUse);+ drop(snapshot);+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+}++#[test]+fn park_images_respects_delay_while_force_park_images_bypasses_it() {+ let (_, manager) = manager(ParkableImagePolicy {+ parking_delay: Duration::from_secs(3600),+ ..ParkableImagePolicy::default()+ });+ let image = manager.from_frozen_bytes(vec![7; 4096]);++ manager.park_images();+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Resident+ );++ manager.force_park_images();+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Parked+ );+ assert_eq!(image.snapshot().unwrap().as_ref(), &[7; 4096]);+}++#[test]+fn forced_sweep_bypasses_deadlines_but_not_live_readers() {+ let (_, manager) = manager(ParkableImagePolicy {+ min_size_to_park: 1,+ parking_delay: Duration::from_secs(30),+ reader_release_delay: Duration::from_secs(30),+ });+ let image = manager.from_frozen_bytes(vec![7; 128]);+ let snapshot = image.snapshot().unwrap();++ let report = manager.force_park_images_with_report();+ assert_eq!(report.in_use, 1);+ assert_eq!(report.parked, 0);++ drop(snapshot);+ let report = manager.force_park_images_with_report();+ assert_eq!(report.parked, 1);+}++#[test]+fn one_extent_round_trips_and_reparks_without_another_write() {+ let (pool, manager) = manager(immediate_policy());+ let bytes = vec![42; 64 * 1024];+ let image = manager.from_frozen_bytes(bytes.clone());++ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Resident+ );+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+ assert_eq!(image.park().unwrap(), ParkOutcome::AlreadyParked);+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Parked+ );+ assert_eq!(pool.diagnostics().disk_footprint_bytes, bytes.len() as u64);+ let snapshot = image.snapshot().unwrap();+ assert_eq!(&*snapshot, bytes);+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::ResidentWithDiskBackup+ );+ assert_eq!(image.park().unwrap(), ParkOutcome::InUse);+ drop(snapshot);++ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Parked+ );+ assert_eq!(pool.diagnostics().disk_footprint_bytes, bytes.len() as u64);+ assert_eq!(image.snapshot().unwrap().as_ref(), bytes);+}++#[test]+fn parked_data_can_be_read_in_segments_and_at_boundaries() {+ let (_, manager) = manager(immediate_policy());+ let bytes = reference_bytes(3 * 4096 + 2048);+ let image = manager.from_frozen_bytes(bytes.clone());+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);++ let mut restored = Vec::new();+ let mut offset = 0;+ while offset < image.len() {+ let segment = image.read_range(offset, 4096).unwrap();+ assert!(!segment.is_empty());+ offset += segment.len();+ restored.extend_from_slice(&segment);+ }++ assert_eq!(restored, bytes);+ assert_eq!(+ image.read_range(image.len(), 4096).unwrap(),+ Vec::<u8>::new()+ );+ assert_eq!(+ image.read_range(image.len() + 1, 4096).unwrap(),+ Vec::<u8>::new()+ );+ assert_eq!(image.read_range(100, 0).unwrap(), Vec::<u8>::new());+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::ResidentWithDiskBackup+ );+}++#[test]+fn snapshot_can_outlive_the_image_and_its_manager() {+ let bytes = reference_bytes(3 * 4096 + 2048);+ let snapshot = {+ let (_, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(bytes.clone());+ image.snapshot().unwrap()+ };++ assert_eq!(&*snapshot, bytes);+}++#[test]+fn live_snapshot_vetoes_parking_without_copying() {+ let (_, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![5; 16]);+ let first = image.snapshot().unwrap();+ let second = first.clone();+ assert_eq!(image.diagnostics().snapshot_count, 2);+ assert_eq!(image.park().unwrap(), ParkOutcome::InUse);+ drop((first, second));+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+}++#[test]+fn below_minimum_and_capacity_failure_keep_memory() {+ let limited_pool = DiskPool::new(Some(4)).unwrap();+ let manager = ParkableImageManager::new(+ Some(limited_pool),+ ParkableImagePolicy {+ min_size_to_park: 2,+ parking_delay: Duration::ZERO,+ reader_release_delay: Duration::ZERO,+ },+ );+ let small = manager.from_frozen_bytes(vec![1]);+ assert_eq!(small.park().unwrap(), ParkOutcome::BelowMinimum);++ let large = manager.from_frozen_bytes(vec![2; 8]);+ assert_eq!(large.park().unwrap(), ParkOutcome::Unavailable);+ assert_eq!(+ large.diagnostics().storage,+ ParkableImageStorageState::Resident+ );+ assert_eq!(large.snapshot().unwrap().as_ref(), vec![2; 8]);+}++#[test]+fn failed_write_keeps_the_image_resident_and_disables_the_pool() {+ let (pool, manager) = manager(immediate_policy());+ let bytes = reference_bytes(3 * 4096 + 2048);+ let image = manager.from_frozen_bytes(bytes.clone());+ pool.fail_next_write_for_test();++ let report = manager.force_park_images_with_report();++ assert_eq!(report.considered, 1);+ assert_eq!(report.write_failures, 1);+ assert!(!pool.may_write());+ assert_eq!(pool.diagnostics().free_bytes, bytes.len());+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Resident+ );+ assert_eq!(image.snapshot().unwrap().as_ref(), bytes);+ assert_eq!(image.park().unwrap(), ParkOutcome::Unavailable);+}++#[test]+fn limited_capacity_is_reclaimed_for_the_next_image() {+ const CAPACITY: usize = 32 * 1024;+ let pool = DiskPool::new(Some(u64::try_from(CAPACITY).unwrap())).unwrap();+ let manager = ParkableImageManager::new(Some(pool.clone()), immediate_policy());+ let first = manager.from_frozen_bytes(vec![1; CAPACITY]);+ let second = manager.from_frozen_bytes(vec![2; CAPACITY]);++ assert_eq!(first.park().unwrap(), ParkOutcome::Parked);+ assert_eq!(second.park().unwrap(), ParkOutcome::Unavailable);+ drop(first);+ assert_eq!(pool.diagnostics().free_bytes, CAPACITY);++ assert_eq!(second.park().unwrap(), ParkOutcome::Parked);+ assert_eq!(pool.diagnostics().disk_footprint_bytes, CAPACITY as u64);+ assert_eq!(second.snapshot().unwrap().as_ref(), vec![2; CAPACITY]);+}++#[test]+fn dropping_a_parked_image_on_another_thread_releases_its_extent() {+ const IMAGE_SIZE: usize = 16 * 1024;+ let (pool, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![3; IMAGE_SIZE]);+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+ assert_eq!(pool.diagnostics().free_bytes, 0);++ std::thread::spawn(move || drop(image)).join().unwrap();++ assert_eq!(pool.diagnostics().free_bytes, IMAGE_SIZE);+ assert_eq!(manager.diagnostics().image_count, 0);+}++#[test]+fn manager_sweeps_only_live_registered_images() {+ let (_, manager) = manager(immediate_policy());+ let first = manager.from_frozen_bytes(vec![1; 8]);+ let second = manager.from_frozen_bytes(vec![2; 8]);+ let small = manager.from_frozen_bytes(Vec::new());+ drop(second);++ let report = manager.force_park_images_with_report();+ assert_eq!(report.considered, 1);+ assert_eq!(report.parked, 1);+ assert_eq!(report.ineligible, 0);+ let diagnostics = manager.diagnostics();+ assert_eq!(diagnostics.image_count, 1);+ assert_eq!(diagnostics.parked_count, 1);+ assert_eq!(diagnostics.resident_count, 0);+ assert_eq!(diagnostics.parking_count, 0);+ assert_eq!(diagnostics.resident_with_disk_backup_count, 0);+ assert!(small.is_empty());+ drop((first, small));+ assert_eq!(manager.diagnostics().image_count, 0);+}++#[test]+fn weak_handle_does_not_extend_image_lifetime() {+ let (_, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![1; 8]);+ let weak = image.downgrade();+ assert!(weak.upgrade().is_some());+ drop(image);+ assert!(weak.upgrade().is_none());+}++#[test]+fn empty_images_are_not_registered_or_parked() {+ let (pool, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(Vec::new());++ assert_eq!(image.park().unwrap(), ParkOutcome::BelowMinimum);+ assert_eq!(manager.diagnostics().image_count, 0);+ assert_eq!(pool.diagnostics().disk_footprint_bytes, 0);+ assert_eq!(pool.diagnostics().free_bytes, 0);+}++#[test]+fn minimum_size_boundary_is_inclusive() {+ const MINIMUM: usize = 4096;+ let (pool, manager) = manager(ParkableImagePolicy {+ min_size_to_park: MINIMUM,+ parking_delay: Duration::ZERO,+ reader_release_delay: Duration::ZERO,+ });+ let below = manager.from_frozen_bytes(vec![1; MINIMUM - 1]);+ let exact = manager.from_frozen_bytes(vec![2; MINIMUM]);++ assert_eq!(below.park().unwrap(), ParkOutcome::BelowMinimum);+ assert_eq!(exact.park().unwrap(), ParkOutcome::Parked);+ assert_eq!(pool.diagnostics().disk_footprint_bytes, MINIMUM as u64);+}++#[test]+fn manager_without_a_pool_reports_unavailable_and_preserves_data() {+ let manager = ParkableImageManager::new(None, immediate_policy());+ let bytes = reference_bytes(4096);+ let image = manager.from_frozen_bytes(bytes.clone());++ let report = manager.force_park_images_with_report();++ assert_eq!(report.considered, 1);+ assert_eq!(report.unavailable, 1);+ assert_eq!(report.parked, 0);+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::Resident+ );+ assert_eq!(image.snapshot().unwrap().as_ref(), bytes);+}++#[test]+fn cloned_handles_share_one_entry_and_release_only_on_last_drop() {+ const IMAGE_SIZE: usize = 8192;+ let (pool, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![7; IMAGE_SIZE]);+ let clone = image.clone();++ assert!(image.shares_storage_with(&clone));+ assert_eq!(manager.diagnostics().image_count, 1);+ assert_eq!(clone.park().unwrap(), ParkOutcome::Parked);+ drop(image);+ assert_eq!(manager.diagnostics().image_count, 1);+ assert_eq!(pool.diagnostics().free_bytes, 0);++ drop(clone);+ assert_eq!(manager.diagnostics().image_count, 0);+ assert_eq!(pool.diagnostics().free_bytes, IMAGE_SIZE);+}++#[test]+fn concurrent_park_attempts_create_only_one_disk_extent() {+ const THREADS: usize = 8;+ let (pool, manager) = manager(immediate_policy());+ let bytes = reference_bytes(128 * 1024);+ let image = manager.from_frozen_bytes(bytes.clone());+ let barrier = std::sync::Arc::new(std::sync::Barrier::new(THREADS));++ let workers = (0..THREADS)+ .map(|_| {+ let image = image.clone();+ let barrier = barrier.clone();+ std::thread::spawn(move || {+ barrier.wait();+ image.park().unwrap()+ })+ })+ .collect::<Vec<_>>();+ let outcomes = workers+ .into_iter()+ .map(|worker| worker.join().unwrap())+ .collect::<Vec<_>>();++ assert_eq!(+ outcomes+ .iter()+ .filter(|&&outcome| outcome == ParkOutcome::Parked)+ .count(),+ 1+ );+ assert!(outcomes.iter().all(|outcome| matches!(+ outcome,+ ParkOutcome::Parked | ParkOutcome::AlreadyParked | ParkOutcome::InUse+ )));+ assert_eq!(pool.diagnostics().disk_footprint_bytes, bytes.len() as u64);+ assert_eq!(image.snapshot().unwrap().as_ref(), bytes);+}++#[test]+fn concurrent_reads_unpark_once_and_preserve_every_copy() {+ const THREADS: usize = 8;+ let (pool, manager) = manager(immediate_policy());+ let bytes = reference_bytes(128 * 1024);+ let image = manager.from_frozen_bytes(bytes.clone());+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+ let barrier = std::sync::Arc::new(std::sync::Barrier::new(THREADS));++ let workers = (0..THREADS)+ .map(|_| {+ let image = image.clone();+ let bytes = bytes.clone();+ let barrier = barrier.clone();+ std::thread::spawn(move || {+ barrier.wait();+ assert_eq!(image.snapshot().unwrap().as_ref(), bytes);+ })+ })+ .collect::<Vec<_>>();+ for worker in workers {+ worker.join().unwrap();+ }++ let diagnostics = image.diagnostics();+ assert_eq!(+ diagnostics.storage,+ ParkableImageStorageState::ResidentWithDiskBackup+ );+ assert_eq!(diagnostics.snapshot_count, 0);+ assert_eq!(pool.diagnostics().disk_footprint_bytes, bytes.len() as u64);+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+}++#[test]+fn next_deadline_tracks_creation_and_the_last_snapshot_release_grace() {+ let delay = Duration::from_secs(30);+ let release_delay = Duration::from_secs(10);+ let wakeups = Arc::new(AtomicUsize::new(0));+ let wakeups_for_callback = Arc::clone(&wakeups);+ let pool = DiskPool::new(None).unwrap();+ let manager = ParkableImageManager::new_with_schedule_wakeup(+ Some(pool),+ ParkableImagePolicy {+ min_size_to_park: 1,+ parking_delay: delay,+ reader_release_delay: release_delay,+ },+ move || {+ wakeups_for_callback.fetch_add(1, Ordering::Relaxed);+ },+ );+ let before_creation = Instant::now();+ let image = manager.from_frozen_bytes(b"encoded image".to_vec());+ let deadline = manager+ .next_parking_deadline()+ .expect("creating an unused eligible image must schedule its delay");+ assert!(deadline >= before_creation + delay);+ assert!(deadline <= Instant::now() + delay);++ let snapshot = image.snapshot().unwrap();+ assert_eq!(+ manager.next_parking_deadline(),+ None,+ "a live snapshot must remove the image from deadline candidates"+ );+ let wakeups_before_drop = wakeups.load(Ordering::Relaxed);+ let before_drop = Instant::now();+ drop(snapshot);+ assert!(wakeups.load(Ordering::Relaxed) > wakeups_before_drop);+ let deadline = manager+ .next_parking_deadline()+ .expect("the last snapshot release must schedule its grace period");+ assert!(deadline >= before_drop + release_delay);+ assert!(deadline <= Instant::now() + release_delay);+ assert!(matches!(image.park().unwrap(), ParkOutcome::Delayed { .. }));+}++#[test]+fn last_snapshot_release_is_visible_before_the_scheduler_wakeup() {+ let manager_slot = Arc::new(Mutex::new(None::<ParkableImageManager>));+ let manager_slot_for_callback = Arc::clone(&manager_slot);+ let wakeups = Arc::new(AtomicUsize::new(0));+ let wakeups_for_callback = Arc::clone(&wakeups);+ let observed_due = Arc::new(AtomicBool::new(false));+ let observed_due_for_callback = Arc::clone(&observed_due);+ let manager = ParkableImageManager::new_with_schedule_wakeup(+ Some(DiskPool::new(None).unwrap()),+ immediate_policy(),+ move || {+ wakeups_for_callback.fetch_add(1, Ordering::SeqCst);+ let manager = manager_slot_for_callback.lock().clone();+ let due = manager.is_some_and(|manager| {+ manager+ .next_parking_deadline()+ .is_some_and(|deadline| deadline <= Instant::now())+ });+ observed_due_for_callback.store(due, Ordering::SeqCst);+ },+ );+ *manager_slot.lock() = Some(manager.clone());+ let image = manager.from_frozen_bytes(vec![7; 4096]);+ let first = image.snapshot().unwrap();+ let second = first.clone();++ observed_due.store(false, Ordering::SeqCst);+ let wakeups_before_drop = wakeups.load(Ordering::SeqCst);+ drop(first);+ assert_eq!(wakeups.load(Ordering::SeqCst), wakeups_before_drop);++ drop(second);+ assert_eq!(wakeups.load(Ordering::SeqCst), wakeups_before_drop + 1);+ assert!(+ observed_due.load(Ordering::SeqCst),+ "the wakeup must observe the reader count after the last lease is released"+ );+}++#[test]+fn concurrent_park_and_unpark_keep_storage_and_registry_aligned() {+ const ITERATIONS: usize = 500;+ let (_, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![5; 4096]);+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+ let start = Arc::new(std::sync::Barrier::new(2));++ let reader = {+ let image = image.clone();+ let start = Arc::clone(&start);+ std::thread::spawn(move || {+ start.wait();+ for _ in 0..ITERATIONS {+ let snapshot = image.snapshot().unwrap();+ assert_eq!(snapshot.len(), 4096);+ drop(snapshot);+ std::thread::yield_now();+ }+ })+ };+ let parker = {+ let image = image.clone();+ let start = Arc::clone(&start);+ std::thread::spawn(move || {+ start.wait();+ for _ in 0..ITERATIONS {+ image.park().unwrap();+ std::thread::yield_now();+ }+ })+ };+ reader.join().unwrap();+ parker.join().unwrap();++ let snapshot = image.snapshot().unwrap();+ drop(snapshot);+ let report = manager.park_images_with_report();+ assert_eq!(report.considered, 1);+ assert_eq!(report.parked, 1);+ assert_eq!(manager.diagnostics().parked_count, 1);+}++#[test]+fn parked_images_leave_the_resident_schedule_until_they_are_unparked() {+ let (_, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![3; 4096]);++ let report = manager.park_images_with_report();+ assert_eq!(report.considered, 1);+ assert_eq!(report.parked, 1);+ assert_eq!(manager.next_parking_deadline(), None);+ assert_eq!(+ manager.force_park_images_with_report().considered,+ 0,+ "the parked registry must not be part of resident sweeps"+ );+ assert_eq!(manager.diagnostics().parked_count, 1);++ let snapshot = image.snapshot().unwrap();+ assert_eq!(manager.diagnostics().parked_count, 0);+ assert_eq!(manager.diagnostics().resident_with_disk_backup_count, 1);+ assert_eq!(manager.next_parking_deadline(), None);+ drop(snapshot);++ let report = manager.park_images_with_report();+ assert_eq!(report.considered, 1);+ assert_eq!(report.parked, 1);+ assert_eq!(manager.diagnostics().parked_count, 1);+}++#[test]+fn capacity_failure_can_be_retried_after_an_extent_is_released() {+ const IMAGE_SIZE: usize = 4096;+ let pool = DiskPool::new(Some(IMAGE_SIZE as u64)).unwrap();+ let released_before_wakeup = Arc::new(AtomicBool::new(false));+ let released_before_wakeup_for_callback = Arc::clone(&released_before_wakeup);+ let pool_for_callback = pool.clone();+ let manager =+ ParkableImageManager::new_with_schedule_wakeup(Some(pool), immediate_policy(), move || {+ if pool_for_callback.diagnostics().free_bytes >= IMAGE_SIZE {+ released_before_wakeup_for_callback.store(true, Ordering::SeqCst);+ }+ });+ let first = manager.from_frozen_bytes(vec![1; IMAGE_SIZE]);+ let second = manager.from_frozen_bytes(vec![2; IMAGE_SIZE]);+ assert_eq!(first.park().unwrap(), ParkOutcome::Parked);++ let report = manager.park_images_with_report();+ assert_eq!(report.considered, 1);+ assert_eq!(report.unavailable, 1);+ assert_eq!(+ manager.next_parking_deadline(),+ None,+ "a capacity miss must wait for a state change instead of spinning on an expired deadline"+ );+ assert_eq!(manager.park_images_with_report().considered, 0);++ released_before_wakeup.store(false, Ordering::SeqCst);+ drop(first);+ assert!(released_before_wakeup.load(Ordering::SeqCst));+ assert!(+ manager+ .next_parking_deadline()+ .is_some_and(|deadline| deadline <= Instant::now()),+ "dropping the parked owner must release its extent before waking the scheduler"+ );+ assert_eq!(manager.park_images_with_report().parked, 1);+ assert_eq!(+ second.diagnostics().storage,+ ParkableImageStorageState::Parked+ );+}++#[test]+fn surviving_snapshot_does_not_keep_the_disk_extent_reserved() {+ const IMAGE_SIZE: usize = 16 * 1024;+ let (pool, manager) = manager(immediate_policy());+ let image = manager.from_frozen_bytes(vec![9; IMAGE_SIZE]);+ assert_eq!(image.park().unwrap(), ParkOutcome::Parked);+ let snapshot = image.snapshot().unwrap();+ assert_eq!(+ image.diagnostics().storage,+ ParkableImageStorageState::ResidentWithDiskBackup+ );++ drop(image);++ assert_eq!(pool.diagnostics().free_bytes, IMAGE_SIZE);+ assert_eq!(&*snapshot, vec![9; IMAGE_SIZE]);+ assert_eq!(manager.diagnostics().image_count, 0);+}