Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Release native generation memory promptly

Bittiaa3d20f664b3
diff --git a/docs/slopfab-compatibility.md b/docs/slopfab-compatibility.md
index 3749590..9db06a3 100644
--- a/docs/slopfab-compatibility.md
+++ b/docs/slopfab-compatibility.md
@@ -1,5 +1,25 @@
# Slopfab compatibility
+## API 1.25: generation sample lifetime
+
+Finished generation cleanup calls `slopfab_generation_release_samples` before
+`slopfab_generation_destroy`. Sample release is optional when loading older
+runtimes; destruction always runs, including if sample release fails. Cleanup
+waits for active native work to stop and excludes sample readers. Slopus saves
+continuation latents to project files and does not need to retain the native
+handle after consuming its output.
+
+Image finalizers consume the single RGBA frame and destroy its native source
+before encoding or writing the image. Video output remains available until
+WebCodecs has consumed its frames and audio. Cancelled, failed, evicted and
+abandoned results use the same ownership cleanup. Requests are destroyed as
+soon as generation starts because Slopfab snapshots them in the start call.
+
+Lifecycle tests use an instrumented C ABI fixture to check release/destruction
+order, request and callback lifetimes, repeated runs, failures, cancellation
+and the older-runtime fallback. A separate test checks that the bundled
+runtime exports the new entry point; these tests do not run model inference.
+
## API 1.24: scene latent upscaling
Scene Generation settings offer an optional **Latent upscale** toggle. Slopus
diff --git a/src-tauri/core/src/slopfab/ffi/handles.rs b/src-tauri/core/src/slopfab/ffi/handles.rs
index 52be292..edfa1d6 100644
--- a/src-tauri/core/src/slopfab/ffi/handles.rs
+++ b/src-tauri/core/src/slopfab/ffi/handles.rs
@@ -19,7 +19,6 @@ pub struct GenerationHandle {
api: Api,
pointer: NonNull<raw::Generation>,
_callback: Option<Box<Callback>>,
- _request: RequestHandle,
terminal: bool,
succeeded: bool,
}
@@ -46,7 +45,9 @@ impl GenerationHandle {
api: request.api.clone(),
pointer,
_callback: callback,
- _request: request,
+ // slopfab_generation_start snapshots the request. Let the caller's
+ // copy (including image/reference samples) drop now instead of
+ // retaining it through inference and the webview's encoding pass.
terminal: false,
succeeded: false,
})
diff --git a/src-tauri/core/src/slopfab/ffi/raw/lifecycle_tests.rs b/src-tauri/core/src/slopfab/ffi/raw/lifecycle_tests.rs
new file mode 100644
index 0000000..d2925a7
--- /dev/null
+++ b/src-tauri/core/src/slopfab/ffi/raw/lifecycle_tests.rs
@@ -0,0 +1,158 @@
+//! Exercise the Rust owners through a small C ABI fixture, without model inference.
+use super::*;
+use super::super::{Api as OwnedApi, RequestHandle};
+use std::{cell::RefCell, sync::{Arc, Mutex}};
+
+#[derive(Default)]
+struct Trace {
+ events: Vec<&'static str>,
+ wait_status: i32,
+ release_status: i32,
+}
+type SharedTrace = Arc<Mutex<Trace>>;
+thread_local! {
+ static TRACE: RefCell<Option<SharedTrace>> = const { RefCell::new(None) };
+}
+struct NativeGeneration {
+ trace: SharedTrace,
+ terminal: bool,
+ samples: Vec<f32>,
+}
+unsafe extern "C" fn create_request() -> *mut Request {
+ TRACE.with(|trace| Box::into_raw(Box::new(trace.borrow().as_ref().unwrap().clone())).cast())
+}
+unsafe extern "C" fn destroy_request(request: *mut Request) {
+ let trace = unsafe { Box::from_raw(request.cast::<SharedTrace>()) };
+ trace.lock().unwrap().events.push("request_destroy");
+}
+unsafe extern "C" fn start(request: *const Request, _: ProgressFn, _: *mut c_void, out: *mut *mut Generation) -> i32 {
+ let trace = unsafe { &*request.cast::<SharedTrace>() }.clone();
+ trace.lock().unwrap().events.push("start");
+ unsafe { *out = Box::into_raw(Box::new(NativeGeneration { trace, terminal: false, samples: vec![0.5; 3] })).cast(); }
+ 0
+}
+unsafe extern "C" fn cancel(generation: *mut Generation) {
+ let generation = unsafe { &mut *generation.cast::<NativeGeneration>() };
+ generation.trace.lock().unwrap().events.push("cancel");
+}
+unsafe extern "C" fn wait(generation: *mut Generation, _: i32) -> i32 {
+ let generation = unsafe { &mut *generation.cast::<NativeGeneration>() };
+ let mut trace = generation.trace.lock().unwrap();
+ trace.events.push("wait");
+ generation.terminal = trace.wait_status != crate::slopfab::NOT_READY;
+ trace.wait_status
+}
+unsafe extern "C" fn output(generation: *const Generation, out: *mut Output) -> i32 {
+ let generation = unsafe { &*generation.cast::<NativeGeneration>() };
+ generation.trace.lock().unwrap().events.push("output");
+ let out = unsafe { &mut *out };
+ out.video = generation.samples.as_ptr();
+ out.video_float_count = generation.samples.len();
+ out.channels = 3;
+ out.width = 1;
+ out.height = 1;
+ out.frames = 1;
+ 0
+}
+unsafe extern "C" fn frame(generation: *const Generation, _: i32, dst: *mut u8, size: usize) -> i32 {
+ let generation = unsafe { &*generation.cast::<NativeGeneration>() };
+ generation.trace.lock().unwrap().events.push("frame");
+ if generation.samples.is_empty() || size != 4 { return -1; }
+ unsafe { std::ptr::copy_nonoverlapping([128, 128, 128, 255].as_ptr(), dst, 4); }
+ 0
+}
+unsafe extern "C" fn release(generation: *mut Generation) -> i32 {
+ let generation = unsafe { &mut *generation.cast::<NativeGeneration>() };
+ let mut trace = generation.trace.lock().unwrap();
+ trace.events.push(if generation.terminal { "release" } else { "release_while_running" });
+ if trace.release_status == 0 { generation.samples = Vec::new(); }
+ trace.release_status
+}
+unsafe extern "C" fn destroy(generation: *mut Generation) {
+ let generation = unsafe { Box::from_raw(generation.cast::<NativeGeneration>()) };
+ generation.trace.lock().unwrap().events.push("destroy");
+}
+unsafe extern "C" fn error(_: *const Generation) -> *const c_char { c"fixture failure".as_ptr() }
+
+fn fixture(release_supported: bool) -> (OwnedApi, SharedTrace) {
+ let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../lib/slopfab").join(crate::slopfab::DLL_FILE_NAME);
+ let mut raw = Api::load(&path).unwrap();
+ raw.request_create = create_request;
+ raw.request_destroy = destroy_request;
+ raw.generation_start = start;
+ raw.generation_wait = wait;
+ raw.generation_cancel = cancel;
+ raw.generation_output = output;
+ raw.generation_frame_rgba8 = frame;
+ raw.generation_error = error;
+ raw.generation_release_samples = release_supported.then_some(release);
+ raw.generation_destroy = destroy;
+ let trace = SharedTrace::default();
+ TRACE.with(|slot| *slot.borrow_mut() = Some(trace.clone()));
+ (OwnedApi { inner: Arc::new(raw), path }, trace)
+}
+
+#[test]
+fn completed_generations_keep_samples_until_consumed_then_release_and_destroy() {
+ let (api, trace) = fixture(true);
+ // Repeated generations must have matching destruction, with no request
+ // snapshot or sample buffer retained by the Rust wrapper between runs.
+ for _ in 0..20 {
+ let mut generation = RequestHandle::new(&api).unwrap().start(None).unwrap();
+ assert_eq!(trace.lock().unwrap().events, ["start", "request_destroy"]);
+ generation.wait(-1).unwrap();
+ let generation = generation.finish().unwrap();
+ assert_eq!(generation.output().unwrap().video_float_count, 3);
+ assert_eq!(generation.frame_rgba8(0, 1, 1).unwrap(), [128, 128, 128, 255]);
+ drop(generation);
+ assert_eq!(trace.lock().unwrap().events, ["start", "request_destroy", "wait", "output", "frame", "release", "destroy"]);
+ trace.lock().unwrap().events.clear();
+ }
+}
+
+#[test]
+fn abandoned_generation_stops_before_releasing_samples_or_callback() {
+ struct CallbackOwner(SharedTrace);
+ impl Drop for CallbackOwner {
+ fn drop(&mut self) { self.0.lock().unwrap().events.push("callback_drop"); }
+ }
+ let (api, trace) = fixture(true);
+ trace.lock().unwrap().wait_status = crate::slopfab::CANCELLED;
+ let owner = CallbackOwner(trace.clone());
+ let sink = Box::new(move |_: &Progress| { let _ = &owner; });
+ let generation = RequestHandle::new(&api).unwrap().start(Some(sink)).unwrap();
+ drop(api); // The generation must retain the DLL through native destruction.
+ drop(generation);
+ assert_eq!(trace.lock().unwrap().events, ["start", "request_destroy", "cancel", "wait", "release", "destroy", "callback_drop"]);
+}
+
+#[test]
+fn failed_generation_releases_without_finishing() {
+ let (api, trace) = fixture(true);
+ trace.lock().unwrap().wait_status = -1;
+ let mut generation = RequestHandle::new(&api).unwrap().start(None).unwrap();
+ assert!(generation.wait(-1).is_err());
+ assert!(generation.finish().is_err());
+ assert_eq!(trace.lock().unwrap().events, ["start", "request_destroy", "wait", "release", "destroy"]);
+}
+
+#[test]
+fn destruction_is_unconditional_when_release_is_missing_or_fails() {
+ for supported in [false, true] {
+ let (api, trace) = fixture(supported);
+ trace.lock().unwrap().release_status = -1;
+ let mut generation = RequestHandle::new(&api).unwrap().start(None).unwrap();
+ generation.wait(-1).unwrap();
+ drop(generation.finish().unwrap());
+ let trace = trace.lock().unwrap();
+ assert_eq!(trace.events.last(), Some(&"destroy"));
+ assert_eq!(trace.events.contains(&"release"), supported);
+ }
+}
+
+#[test]
+fn bundled_runtime_exports_sample_release() {
+ let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../lib/slopfab").join(crate::slopfab::DLL_FILE_NAME);
+ let api = Api::load(&path).unwrap();
+ assert!(api.generation_release_samples.is_some());
+}
diff --git a/src-tauri/core/src/slopfab/ffi/raw/mod.rs b/src-tauri/core/src/slopfab/ffi/raw/mod.rs
index 97d148e..d4d9ec1 100644
--- a/src-tauri/core/src/slopfab/ffi/raw/mod.rs
+++ b/src-tauri/core/src/slopfab/ffi/raw/mod.rs
@@ -115,6 +115,7 @@ pub struct Api {
generation_error: unsafe extern "C" fn(*const Generation) -> *const c_char,
generation_output: unsafe extern "C" fn(*const Generation, *mut Output) -> i32,
generation_frame_rgba8: unsafe extern "C" fn(*const Generation, i32, *mut u8, usize) -> i32,
+ generation_release_samples: Option<unsafe extern "C" fn(*mut Generation) -> i32>,
generation_destroy: unsafe extern "C" fn(*mut Generation),
}
@@ -326,6 +327,12 @@ impl Api {
"slopfab_generation_destroy",
unsafe extern "C" fn(*mut Generation)
),
+ generation_release_samples: library
+ .get::<unsafe extern "C" fn(*mut Generation) -> i32>(
+ b"slopfab_generation_release_samples\0",
+ )
+ .ok()
+ .map(|symbol| *symbol),
_library: library,
})
}
@@ -674,9 +681,20 @@ impl Api {
Ok(rgba)
}
pub fn destroy_generation(&self, generation: *mut Generation) {
+ // The owner has stopped the worker and excludes all sample readers.
+ // API 1.25 releases the large decoded buffers explicitly. Destruction
+ // remains unconditional: it also frees retained latents and request
+ // inputs, and is the complete cleanup path for older runtimes.
+ if let Some(release) = self.generation_release_samples {
+ unsafe { release(generation); }
+ }
unsafe { (self.generation_destroy)(generation) }
}
}
+
+#[cfg(test)]
+#[path = "lifecycle_tests.rs"]
+mod lifecycle_tests;
fn path_cstring(path: &Path) -> Result<CString, String> {
CString::new(path.to_string_lossy().as_bytes())
.map_err(|_| "A slopfab path contains a null byte.".into())
diff --git a/src-tauri/core/src/slopfab/icons.rs b/src-tauri/core/src/slopfab/icons.rs
index a407dd4..6750070 100644
--- a/src-tauri/core/src/slopfab/icons.rs
+++ b/src-tauri/core/src/slopfab/icons.rs
@@ -81,6 +81,7 @@ pub(super) fn write_reference_icon(
));
}
let rgba = generation.frame_rgba8(0, render_size, render_size)?;
+ drop(generation);
let jpeg = crate::reference_icons::encode_jpeg(&rgba)?;
if let Some(parent) = spec.destination.parent() {
std::fs::create_dir_all(parent).map_err(|error| {