feat(async)!: make AsyncSCStream lifecycle methods truly async

start_capture/stop_capture/update_configuration/update_content_filter on
AsyncSCStream now return a waker-based StreamControlFuture instead of blocking
the calling thread on a condition variable. Awaiting parks the task via its
Waker and resumes from the Swift completion callback, so they no longer stall
single-threaded/current-thread executors. This makes the async surface fully
waker-based and consistent with the Swift Task { try await } entry points.

- add stream_control_callback bridging (context,success,msg) -> AsyncCompletion
- StreamControlFuture is Send (spawnable); asserted by a compile-time test
- update doctests, 08_async example, and tests (sync setup -> inner(), async -> await)
- document the breaking change in CHANGELOG and MIGRATION

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 1313

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- [**breaking**] `AsyncSCStream::start_capture`, `stop_capture`, `update_configuration`,
+  and `update_content_filter` are now genuinely async: they return a
+  `StreamControlFuture` (resolving to `Result<(), SCError>`) that you `.await`,
+  instead of blocking the calling thread on a condition variable. Awaiting them
+  parks the task via its `Waker` and resumes from the Swift completion callback,
+  so they no longer stall single-threaded/current-thread executors. This makes
+  the async surface fully waker-based and consistent with the underlying Swift
+  `Task { try await … }` entry points.
+
+  Migration: add `.await` (e.g. `stream.start_capture().await?`). For a
+  blocking call, use the synchronous `SCStream` directly via
+  `stream.inner().start_capture()`.
+
+### Added
+
+- `async_api::StreamControlFuture` — the `Send` future returned by the
+  `AsyncSCStream` lifecycle methods.
+
 ## [7.0.1](https://github.com/doom-fish/screencapturekit-rs/compare/v7.0.0...v7.0.1) - 2026-06-06
 
 ### Fixed

docs/MIGRATION.md

@@ -212,6 +212,39 @@ low-level changes:
 Everything else is internal: `MaybeUninit` scratch buffers for batched FFI
 calls, null-checked constructors, and consolidated retain/release wrappers.
 
+## Migrating to the next major version (unreleased)
+
+The `async` stream lifecycle methods are now genuinely asynchronous. Previously
+`AsyncSCStream::start_capture` / `stop_capture` / `update_configuration` /
+`update_content_filter` returned `Result<(), SCError>` and **blocked the calling
+thread** on a condition variable until ScreenCaptureKit acknowledged the
+operation — which stalls single-threaded / current-thread executors. They now
+return a `StreamControlFuture` you `.await`:
+
+```diff
+- stream.start_capture()?;
+- stream.stop_capture()?;
++ stream.start_capture().await?;
++ stream.stop_capture().await?;
+```
+
+```diff
+- stream.update_configuration(&config)?;
+- stream.update_content_filter(&filter)?;
++ stream.update_configuration(&config).await?;
++ stream.update_content_filter(&filter).await?;
+```
+
+Awaiting now parks the task via its `Waker` and resumes from the Swift
+completion callback, so it never blocks the executor — matching the rest of the
+`async_api` (content queries, screenshots, picker, frame iteration) and the
+underlying Swift `Task { try await … }` entry points. The returned
+`StreamControlFuture` is `Send`, so it can be moved across `tokio::spawn`.
+
+If you specifically want a **blocking** call (e.g. from synchronous code), reach
+through to the synchronous stream with `stream.inner().start_capture()` — the
+`SCStream` methods are unchanged.
+
 ## Migrating from 0.x to 1.0
 
 Version 1.0 introduced a complete API redesign with builder patterns, async support, and new macOS features.

examples/08_async.rs

@@ -159,7 +159,9 @@ async fn async_stream_iteration() -> Result<(), Box<dyn std::error::Error>> {
 
         // Create async stream with 30-frame buffer
         let stream = AsyncSCStream::new(&filter, &config, 30, SCStreamOutputType::Screen);
-        stream.start_capture()?;
+        // start/stop are truly async: awaiting parks the task via its Waker and
+        // resumes from the Swift completion callback — the executor is never blocked.
+        stream.start_capture().await?;
 
         println!("   Capturing frames asynchronously...");
 
@@ -174,7 +176,7 @@ async fn async_stream_iteration() -> Result<(), Box<dyn std::error::Error>> {
             }
         }
 
-        stream.stop_capture()?;
+        stream.stop_capture().await?;
         println!("   ✅ Captured {count} frames");
     } else {
         println!("   ⚠️  No displays available");

src/async_api.rs

@@ -52,7 +52,7 @@
 //! let config = SCStreamConfiguration::new().with_width(1920).with_height(1080);
 //!
 //! let stream = AsyncSCStream::new(&filter, &config, 30, SCStreamOutputType::Screen);
-//! stream.start_capture()?;
+//! stream.start_capture().await?;
 //!
 //! // Process frames asynchronously
 //! for _ in 0..100 {
@@ -61,7 +61,7 @@
 //!     }
 //! }
 //!
-//! stream.stop_capture()?;
+//! stream.stop_capture().await?;
 //! # Ok(())
 //! # }
 //! ```
@@ -399,6 +399,67 @@ impl Future for NextSample<'_> {
 unsafe impl Send for AsyncSampleSender {}
 unsafe impl Sync for AsyncSampleSender {}
 
+// ----------------------------------------------------------------------------
+// Stream lifecycle control futures (start / stop / update)
+// ----------------------------------------------------------------------------
+
+/// FFI completion callback for [`AsyncSCStream`] lifecycle operations.
+///
+/// Translates the Swift `(context, success, message)` completion into the
+/// waker-based [`AsyncCompletion`] machinery, so awaiting a control future
+/// resumes the task via its [`Waker`] instead of parking a thread. This is the
+/// same primitive used by the content / screenshot / picker futures.
+extern "C" fn stream_control_callback(context: *mut c_void, success: bool, msg: *const i8) {
+    crate::utils::panic_safe::catch_user_panic("stream_control_callback", move || {
+        if success {
+            // SAFETY: `context` is the one-shot completion pointer from
+            // `AsyncCompletion::<()>::create()`; Swift invokes this callback
+            // exactly once, after which the pointer is consumed.
+            unsafe { AsyncCompletion::<()>::complete_ok(context, ()) };
+        } else {
+            let error = unsafe { error_from_cstr(msg) };
+            // SAFETY: see above — one-shot completion pointer, fired once.
+            unsafe { AsyncCompletion::<()>::complete_err(context, error) };
+        }
+    });
+}
+
+/// Future for an [`AsyncSCStream`] lifecycle operation — `start_capture`,
+/// `stop_capture`, `update_configuration`, or `update_content_filter`.
+///
+/// Resolves once `ScreenCaptureKit` acknowledges the operation. Awaiting it
+/// **never blocks the executor thread**: the task is parked via its [`Waker`]
+/// and resumed from the Swift completion callback. This mirrors the underlying
+/// Swift `Task { try await … }` entry points, keeping the async surface
+/// consistent end to end.
+///
+/// The operation is kicked off eagerly when the method is called (a "hot"
+/// future), matching the rest of this module — e.g.
+/// [`AsyncSCShareableContent::get`]. Dropping the future without awaiting is
+/// safe; it simply means success/failure is not observed.
+#[must_use = "the operation starts eagerly, but you must .await the future to observe success or failure"]
+pub struct StreamControlFuture {
+    inner: AsyncCompletionFuture<()>,
+    map_err: fn(String) -> SCError,
+}
+
+impl std::fmt::Debug for StreamControlFuture {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("StreamControlFuture").finish_non_exhaustive()
+    }
+}
+
+impl Future for StreamControlFuture {
+    type Output = Result<(), SCError>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let map_err = self.map_err;
+        Pin::new(&mut self.inner)
+            .poll(cx)
+            .map(|r| r.map_err(map_err))
+    }
+}
+
 /// Async wrapper for `SCStream` with integrated frame iteration
 ///
 /// Provides async methods for stream lifecycle and frame iteration.
@@ -421,7 +482,7 @@ unsafe impl Sync for AsyncSampleSender {}
 ///     .with_height(1080);
 ///
 /// let stream = AsyncSCStream::new(&filter, &config, 30, SCStreamOutputType::Screen);
-/// stream.start_capture()?;
+/// stream.start_capture().await?;
 ///
 /// // Process frames asynchronously
 /// while let Some(frame) = stream.next().await {
@@ -527,40 +588,113 @@ impl AsyncSCStream {
         }
     }
 
-    /// Start capture (synchronous - returns immediately)
+    /// Start capture asynchronously.
+    ///
+    /// Resolves when `ScreenCaptureKit` confirms the stream has started.
+    /// Unlike [`SCStream::start_capture`](crate::stream::SCStream::start_capture),
+    /// awaiting this **does not block the executor thread** — the task is parked
+    /// via its [`Waker`] and resumed from the Swift completion callback.
+    ///
+    /// The capture is initiated eagerly when this method is called; `.await`
+    /// observes the completion (or error).
     ///
     /// # Errors
     ///
-    /// Returns an error if capture fails to start.
-    pub fn start_capture(&self) -> Result<(), SCError> {
-        self.stream.start_capture()
+    /// The awaited result is `Err(SCError::CaptureStartFailed)` if the stream
+    /// fails to start.
+    pub fn start_capture(&self) -> StreamControlFuture {
+        let (future, context) = AsyncCompletion::<()>::create();
+        // SAFETY: `self.stream.as_ptr()` is a valid, live `SCStream` pointer for
+        // the duration of this call; `context` is the one-shot completion
+        // pointer from `AsyncCompletion::create()`, invoked exactly once.
+        unsafe {
+            crate::ffi::sc_stream_start_capture(
+                self.stream.as_ptr(),
+                context,
+                stream_control_callback,
+            );
+        }
+        StreamControlFuture {
+            inner: future,
+            map_err: SCError::CaptureStartFailed,
+        }
     }
 
-    /// Stop capture (synchronous - returns immediately)
+    /// Stop capture asynchronously.
+    ///
+    /// Resolves when `ScreenCaptureKit` confirms the stream has stopped. Awaiting
+    /// this **does not block the executor thread**.
     ///
     /// # Errors
     ///
-    /// Returns an error if capture fails to stop.
-    pub fn stop_capture(&self) -> Result<(), SCError> {
-        self.stream.stop_capture()
+    /// The awaited result is `Err(SCError::CaptureStopFailed)` if the stream
+    /// fails to stop.
+    pub fn stop_capture(&self) -> StreamControlFuture {
+        let (future, context) = AsyncCompletion::<()>::create();
+        // SAFETY: see `start_capture` — live stream pointer, one-shot context.
+        unsafe {
+            crate::ffi::sc_stream_stop_capture(
+                self.stream.as_ptr(),
+                context,
+                stream_control_callback,
+            );
+        }
+        StreamControlFuture {
+            inner: future,
+            map_err: SCError::CaptureStopFailed,
+        }
     }
 
-    /// Update stream configuration
+    /// Update stream configuration asynchronously.
+    ///
+    /// Resolves when the reconfiguration completes. Awaiting this **does not
+    /// block the executor thread**.
     ///
     /// # Errors
     ///
-    /// Returns an error if the update fails.
-    pub fn update_configuration(&self, config: &SCStreamConfiguration) -> Result<(), SCError> {
-        self.stream.update_configuration(config)
+    /// The awaited result is `Err(SCError::StreamError)` if the update fails.
+    pub fn update_configuration(&self, config: &SCStreamConfiguration) -> StreamControlFuture {
+        let (future, context) = AsyncCompletion::<()>::create();
+        // SAFETY: `self.stream.as_ptr()` and `config.as_ptr()` are valid for the
+        // duration of this call; `context` is the one-shot completion pointer.
+        unsafe {
+            crate::ffi::sc_stream_update_configuration(
+                self.stream.as_ptr(),
+                config.as_ptr(),
+                context,
+                stream_control_callback,
+            );
+        }
+        StreamControlFuture {
+            inner: future,
+            map_err: SCError::StreamError,
+        }
     }
 
-    /// Update content filter
+    /// Update content filter asynchronously.
+    ///
+    /// Resolves when the filter swap completes. Awaiting this **does not block
+    /// the executor thread**.
     ///
     /// # Errors
     ///
-    /// Returns an error if the update fails.
-    pub fn update_content_filter(&self, filter: &SCContentFilter) -> Result<(), SCError> {
-        self.stream.update_content_filter(filter)
+    /// The awaited result is `Err(SCError::StreamError)` if the update fails.
+    pub fn update_content_filter(&self, filter: &SCContentFilter) -> StreamControlFuture {
+        let (future, context) = AsyncCompletion::<()>::create();
+        // SAFETY: `self.stream.as_ptr()` and `filter.as_ptr()` are valid for the
+        // duration of this call; `context` is the one-shot completion pointer.
+        unsafe {
+            crate::ffi::sc_stream_update_content_filter(
+                self.stream.as_ptr(),
+                filter.as_ptr(),
+                context,
+                stream_control_callback,
+            );
+        }
+        StreamControlFuture {
+            inner: future,
+            map_err: SCError::StreamError,
+        }
     }
 
     /// Get a reference to the underlying stream