Skip to content

armgit / moli

Public Imported from GitHub
0

Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust

feat(parkable-image): add managed encoded image parking

ldm00099465abc98
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index 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.toml
new file mode 100644
index 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 = true
diff --git a/moli-parkable-image/README.md b/moli-parkable-image/README.md
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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);
+}