diff --git a/native/Cargo.toml b/native/Cargo.toml index e76de63..52aa35e 100644 --- a/native/Cargo.toml +++ b/native/Cargo.toml @@ -33,8 +33,9 @@ datafusion-table-providers = { version = "0.11", default-features = false, optio futures = "0.3" object_store = { version = "0.13", default-features = false } prost = "0.14" -tokio = { version = "1", features = ["rt-multi-thread"] } +tokio = { version = "1", features = ["rt-multi-thread", "macros"] } tokio-metrics = { version = "0.5", optional = true } +tokio-util = { version = "0.7", features = ["rt"] } url = "2" [build-dependencies] diff --git a/native/src/cancellation.rs b/native/src/cancellation.rs new file mode 100644 index 0000000..c234030 --- /dev/null +++ b/native/src/cancellation.rs @@ -0,0 +1,147 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! Cancellation tokens for in-flight queries. +//! +//! Managed handles are opaque `u64` IDs, not raw pointers. A process-global +//! registry maps each live ID to its `Arc`. FFI handlers +//! look up by ID and clone the `Arc` out of the registry (under a lock) so a +//! concurrent free can never invalidate a borrow already in flight: the worst +//! a race produces is a token that no longer cancels anything, never a +//! use-after-free of a freed `Box`. +//! +//! The C# layer owns one token per cancellable `collect`/`execute_stream` +//! call and fires it from the thread that owns the managed `CancellationToken` +//! while the calling thread is parked inside `runtime().block_on(...)`. + +use std::collections::HashMap; +use std::os::raw::c_int; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex, OnceLock}; + +use datafusion::error::DataFusionError; +use tokio_util::sync::CancellationToken; + +use crate::take_result; + +/// Sentinel message used to round-trip a query-cancellation signal across the +/// FFI boundary. A cancelled `collect`/`execute_stream` returns a +/// `DataFusionError::Execution` carrying this message; the C# side maps it to +/// an `OperationCanceledException` whenever the managed token also reports a +/// cancellation request. +pub(crate) const CANCELLED_MESSAGE: &str = "datafusion-csharp: query cancelled"; + +fn registry() -> &'static Mutex>> { + static REG: OnceLock>>> = OnceLock::new(); + REG.get_or_init(|| Mutex::new(HashMap::new())) +} + +fn next_id() -> u64 { + // Start at 1 so 0 stays reserved as the "no token" sentinel on the managed + // side. Monotonic; 2^64 IDs is enough that reuse is never observed. + static COUNTER: AtomicU64 = AtomicU64::new(1); + COUNTER.fetch_add(1, Ordering::Relaxed) +} + +/// Resolve a token handle into an `Arc`, or `None` when the +/// handle is the zero "no token" sentinel or refers to an already-freed entry. +/// The cloned `Arc` keeps the inner token alive for the borrow's lifetime, so a +/// concurrent `df_cancellation_token_free` removing the registry entry is safe. +pub(crate) fn token_arc(handle: u64) -> Option> { + if handle == 0 { + return None; + } + let guard = registry().lock().expect("cancellation registry poisoned"); + guard.get(&handle).cloned() +} + +#[no_mangle] +pub extern "C" fn df_cancellation_token_new(out: *mut u64) -> c_int { + take_result(|| { + if out.is_null() { + return Err("output token handle pointer is null".into()); + } + let token: Arc = Arc::new(CancellationToken::new()); + let id = next_id(); + registry() + .lock() + .expect("cancellation registry poisoned") + .insert(id, token); + unsafe { + *out = id; + } + Ok(()) + }) +} + +#[no_mangle] +pub extern "C" fn df_cancellation_token_cancel(handle: u64) -> c_int { + take_result(|| { + // A missing entry (already freed or never registered) is a no-op: the + // C# wrapper disposes its registration before freeing, so a real cancel + // never loses a race, and a defensive no-op avoids spurious failures. + if let Some(token) = token_arc(handle) { + token.cancel(); + } + Ok(()) + }) +} + +#[no_mangle] +pub extern "C" fn df_cancellation_token_free(handle: u64) -> c_int { + take_result(|| { + if handle != 0 { + // Remove the registry entry; the underlying `Arc` may still have + // clones held by an in-flight collect/execute_stream future, which + // keep the inner token alive until those futures finish. + registry() + .lock() + .expect("cancellation registry poisoned") + .remove(&handle); + } + Ok(()) + }) +} + +fn cancelled_error() -> DataFusionError { + DataFusionError::Execution(CANCELLED_MESSAGE.to_string()) +} + +/// Drive `fut` to completion unless `token` fires first. A fired token yields a +/// `DataFusionError::Execution(CANCELLED_MESSAGE)` so the managed side can +/// surface a cancellation. `biased` polls the cancellation branch first so a +/// token that is already cancelled aborts before any query work runs. +pub(crate) async fn run_cancellable( + token: &Option>, + fut: F, +) -> Result +where + F: std::future::Future>, +{ + let Some(token) = token else { + return fut.await; + }; + tokio::select! { + biased; + _ = token.cancelled() => Err(cancelled_error()), + result = fut => result, + } +} + +pub(crate) fn resolve_token(handle: u64) -> Option> { + token_arc(handle) +} diff --git a/native/src/lib.rs b/native/src/lib.rs index 4943202..e1f55b7 100644 --- a/native/src/lib.rs +++ b/native/src/lib.rs @@ -50,6 +50,7 @@ use tokio::runtime::Runtime; mod arrow; mod avro; mod cache_manager; +mod cancellation; mod clickhouse; mod csv; mod json; @@ -72,6 +73,7 @@ mod proto_gen { use crate::arrow::arrow_options; use crate::avro::avro_options; +use crate::cancellation::{resolve_token, run_cancellable}; use crate::csv::csv_options; use crate::json::json_options; use crate::parquet::parquet_options; @@ -721,12 +723,14 @@ pub extern "C" fn df_dataframe_schema_ipc(handle: *mut DataFrame, out: *mut DfBy #[no_mangle] pub extern "C" fn df_dataframe_collect_ipc( handle: *mut DataFrame, + token_handle: u64, out: *mut DfByteBuffer, ) -> c_int { take_result(|| { let df = unsafe { *Box::from_raw(require_ptr(handle, "DataFrame handle")?) }; + let token = resolve_token(token_handle); let schema: SchemaRef = Arc::new(df.schema().as_arrow().clone()); - let batches = runtime().block_on(df.collect())?; + let batches = runtime().block_on(run_cancellable(&token, df.collect()))?; write_buffer(out, batches_ipc(schema, batches)?) }) } @@ -734,19 +738,21 @@ pub extern "C" fn df_dataframe_collect_ipc( #[no_mangle] pub extern "C" fn df_dataframe_execute_stream_ipc( handle: *mut DataFrame, + token_handle: u64, out: *mut DfByteBuffer, ) -> c_int { take_result(|| { let df = unsafe { *Box::from_raw(require_ptr(handle, "DataFrame handle")?) }; + let token = resolve_token(token_handle); let schema: SchemaRef = Arc::new(df.schema().as_arrow().clone()); - let mut stream = runtime().block_on(df.execute_stream())?; - let batches = runtime().block_on(async { + let batches = runtime().block_on(run_cancellable(&token, async move { + let mut stream = df.execute_stream().await?; let mut batches = Vec::new(); while let Some(batch) = stream.next().await { batches.push(batch?); } Ok::<_, DataFusionError>(batches) - })?; + }))?; write_buffer(out, batches_ipc(schema, batches)?) }) } diff --git a/src/Apache.DataFusion/DataFrame/DataFrame.Execution.cs b/src/Apache.DataFusion/DataFrame/DataFrame.Execution.cs index 85421eb..ea13550 100644 --- a/src/Apache.DataFusion/DataFrame/DataFrame.Execution.cs +++ b/src/Apache.DataFusion/DataFrame/DataFrame.Execution.cs @@ -22,23 +22,67 @@ namespace Apache.DataFusion; public sealed partial class DataFrame { - public ArrowBatchReader Collect() + public ArrowBatchReader Collect() => Collect(CancellationToken.None); + + /// + /// Execute the plan with cooperative cancellation. Firing + /// from another thread aborts the + /// in-flight query at its next poll point and throws + /// . A token that cannot be + /// cancelled (e.g. ) behaves exactly + /// like the parameterless overload. + /// + public ArrowBatchReader Collect(CancellationToken cancellationToken) { - return new ArrowBatchReader(CollectIpcBytes()); + return new ArrowBatchReader(CollectIpcBytes(cancellationToken)); } - internal byte[] CollectIpcBytes() + internal byte[] CollectIpcBytes() => CollectIpcBytes(CancellationToken.None); + + internal byte[] CollectIpcBytes(CancellationToken cancellationToken) { IntPtr current = TakeHandle(); - NativeMethods.Check(NativeMethods.df_dataframe_collect_ipc(current, out NativeMethods.ByteBuffer buffer)); - return NativeMethods.CopyAndFree(buffer); + if (!cancellationToken.CanBeCanceled) + { + NativeMethods.Check(NativeMethods.df_dataframe_collect_ipc(current, 0UL, out NativeMethods.ByteBuffer buffer)); + return NativeMethods.CopyAndFree(buffer); + } + + using NativeCancellationToken token = NativeCancellationToken.Create(); + using (cancellationToken.Register(static state => ((NativeCancellationToken)state!).Cancel(), token)) + { + int status = NativeMethods.df_dataframe_collect_ipc(current, token.Handle, out NativeMethods.ByteBuffer buffer); + NativeMethods.CheckCancellable(status, cancellationToken); + return NativeMethods.CopyAndFree(buffer); + } } - public ArrowBatchReader ExecuteStream() + public ArrowBatchReader ExecuteStream() => ExecuteStream(CancellationToken.None); + + /// + /// Execute the plan and materialize the result with cooperative + /// cancellation. Firing from another + /// thread aborts the in-flight query at its next poll point and throws + /// . A token that cannot be + /// cancelled (e.g. ) behaves exactly + /// like the parameterless overload. + /// + public ArrowBatchReader ExecuteStream(CancellationToken cancellationToken) { IntPtr current = TakeHandle(); - NativeMethods.Check(NativeMethods.df_dataframe_execute_stream_ipc(current, out NativeMethods.ByteBuffer buffer)); - return new ArrowBatchReader(NativeMethods.CopyAndFree(buffer)); + if (!cancellationToken.CanBeCanceled) + { + NativeMethods.Check(NativeMethods.df_dataframe_execute_stream_ipc(current, 0UL, out NativeMethods.ByteBuffer buffer)); + return new ArrowBatchReader(NativeMethods.CopyAndFree(buffer)); + } + + using NativeCancellationToken token = NativeCancellationToken.Create(); + using (cancellationToken.Register(static state => ((NativeCancellationToken)state!).Cancel(), token)) + { + int status = NativeMethods.df_dataframe_execute_stream_ipc(current, token.Handle, out NativeMethods.ByteBuffer buffer); + NativeMethods.CheckCancellable(status, cancellationToken); + return new ArrowBatchReader(NativeMethods.CopyAndFree(buffer)); + } } public byte[] SchemaIpc() diff --git a/src/Apache.DataFusion/Interop/NativeCancellationToken.cs b/src/Apache.DataFusion/Interop/NativeCancellationToken.cs new file mode 100644 index 0000000..9ce0d59 --- /dev/null +++ b/src/Apache.DataFusion/Interop/NativeCancellationToken.cs @@ -0,0 +1,64 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +namespace Apache.DataFusion.Interop; + +/// +/// Owns a native cancellation token registered in the process-global registry. +/// One instance bridges a managed to an +/// in-flight native query: when the managed token fires, +/// signals the native token so a query parked inside the blocking FFI call +/// aborts at its next poll point. +/// +internal sealed class NativeCancellationToken : IDisposable +{ + // Stored as long (not ulong) so Interlocked can guard the close/cancel race. + // The native registry hands out monotonically increasing IDs starting at 1, + // so the value never approaches the signed range and 0 is the freed sentinel. + private long handle; + + private NativeCancellationToken(long handle) + { + this.handle = handle; + } + + public static NativeCancellationToken Create() + { + NativeMethods.Check(NativeMethods.df_cancellation_token_new(out ulong handle)); + return new NativeCancellationToken((long)handle); + } + + public ulong Handle => (ulong)Interlocked.Read(ref handle); + + public void Cancel() + { + long current = Interlocked.Read(ref handle); + if (current != 0) + { + NativeMethods.Check(NativeMethods.df_cancellation_token_cancel((ulong)current)); + } + } + + public void Dispose() + { + long current = Interlocked.Exchange(ref handle, 0); + if (current != 0) + { + NativeMethods.Check(NativeMethods.df_cancellation_token_free((ulong)current)); + } + } +} diff --git a/src/Apache.DataFusion/Interop/NativeMethods/CancellationNativeMethods.cs b/src/Apache.DataFusion/Interop/NativeMethods/CancellationNativeMethods.cs new file mode 100644 index 0000000..a07aa4c --- /dev/null +++ b/src/Apache.DataFusion/Interop/NativeMethods/CancellationNativeMethods.cs @@ -0,0 +1,52 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +using System.Runtime.InteropServices; + +namespace Apache.DataFusion.Interop; + +internal static partial class NativeMethods +{ + [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)] + internal static extern int df_cancellation_token_new(out ulong handle); + + [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)] + internal static extern int df_cancellation_token_cancel(ulong handle); + + [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)] + internal static extern int df_cancellation_token_free(ulong handle); + + internal static void CheckCancellable(int status, CancellationToken cancellationToken) + { + if (status == 0) + { + return; + } + + // A non-zero status after a cancellation request is the native query + // aborting on our token. The native token is only ever fired through + // the managed token's registered callback, so a cancelled native query + // implies the managed token is cancelled too. Surface the idiomatic + // OperationCanceledException rather than the raw DataFusion error. + if (cancellationToken.IsCancellationRequested) + { + throw new OperationCanceledException(cancellationToken); + } + + Check(status); + } +} diff --git a/src/Apache.DataFusion/Interop/NativeMethods/DataFrameNativeMethods.cs b/src/Apache.DataFusion/Interop/NativeMethods/DataFrameNativeMethods.cs index 59fb166..54e7aa2 100644 --- a/src/Apache.DataFusion/Interop/NativeMethods/DataFrameNativeMethods.cs +++ b/src/Apache.DataFusion/Interop/NativeMethods/DataFrameNativeMethods.cs @@ -28,10 +28,10 @@ internal static partial class NativeMethods internal static extern int df_dataframe_schema_ipc(IntPtr handle, out ByteBuffer buffer); [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)] - internal static extern int df_dataframe_collect_ipc(IntPtr handle, out ByteBuffer buffer); + internal static extern int df_dataframe_collect_ipc(IntPtr handle, ulong tokenHandle, out ByteBuffer buffer); [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)] - internal static extern int df_dataframe_execute_stream_ipc(IntPtr handle, out ByteBuffer buffer); + internal static extern int df_dataframe_execute_stream_ipc(IntPtr handle, ulong tokenHandle, out ByteBuffer buffer); [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)] internal static extern int df_dataframe_count(IntPtr handle, out ulong count); diff --git a/tests/Apache.DataFusion.Tests/DataFrame/DataFrameCancellationTests.cs b/tests/Apache.DataFusion.Tests/DataFrame/DataFrameCancellationTests.cs new file mode 100644 index 0000000..f8be6e1 --- /dev/null +++ b/tests/Apache.DataFusion.Tests/DataFrame/DataFrameCancellationTests.cs @@ -0,0 +1,119 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +using Apache.Arrow; + +namespace Apache.DataFusion.Tests; + +public sealed class DataFrameCancellationTests +{ + [Fact] + public void PreCancelledTokenAbortsCollect() + { + using SessionContext context = new(); + using CancellationTokenSource cts = new(); + cts.Cancel(); + + using DataFrame dataFrame = context.Sql("SELECT * FROM (VALUES (1), (2), (3)) AS t(x)"); + + Assert.Throws(() => dataFrame.Collect(cts.Token)); + } + + [Fact] + public void PreCancelledTokenAbortsExecuteStream() + { + using SessionContext context = new(); + using CancellationTokenSource cts = new(); + cts.Cancel(); + + using DataFrame dataFrame = context.Sql("SELECT * FROM (VALUES (1), (2), (3)) AS t(x)"); + + Assert.Throws(() => dataFrame.ExecuteStream(cts.Token)); + } + + [Fact] + public async Task UnfiredTokenCollectsAllRows() + { + using SessionContext context = new(); + using CancellationTokenSource cts = new(); + + using DataFrame dataFrame = context.Sql("SELECT * FROM (VALUES (1), (2), (3), (4)) AS t(x)"); + using ArrowBatchReader reader = dataFrame.Collect(cts.Token); + + Assert.Equal(4, await CountRowsAsync(reader)); + } + + [Fact] + public async Task NoneTokenBehavesLikeParameterlessOverload() + { + using SessionContext context = new(); + + using DataFrame collected = context.Sql("SELECT * FROM (VALUES (1), (2), (3)) AS t(x)"); + using ArrowBatchReader collectReader = collected.Collect(CancellationToken.None); + Assert.Equal(3, await CountRowsAsync(collectReader)); + + using DataFrame streamed = context.Sql("SELECT * FROM (VALUES (1), (2), (3)) AS t(x)"); + using ArrowBatchReader streamReader = streamed.ExecuteStream(CancellationToken.None); + Assert.Equal(3, await CountRowsAsync(streamReader)); + } + + [Fact] + public async Task CancelMidCollectAbortsBeforeCompletion() + { + ManualResetEventSlim firstInvocation = new(initialState: false); + + using SessionContext context = SessionContext.CreateBuilder().BatchSize(1).Build(); + context.RegisterScalarUdf(ScalarUdf.Int64( + "sleep_identity", + _ => + { + firstInvocation.Set(); + Thread.Sleep(50); + return ColumnarValue.Int64(1); + }, + Volatility.Volatile)); + + using CancellationTokenSource cts = new(); + + // ~1000 * 50ms is far longer than the wait below, so the assertion only + // passes if cancellation actually aborts the in-flight collect. + using DataFrame dataFrame = context.Sql( + "SELECT sleep_identity() AS y FROM generate_series(1, 1000)"); + + Task task = Task.Run(() => dataFrame.Collect(cts.Token)); + + Assert.True(firstInvocation.Wait(TimeSpan.FromSeconds(10)), "UDF should have been invoked at least once"); + cts.Cancel(); + + await Assert.ThrowsAnyAsync(async () => + { + using ArrowBatchReader _ = await task.WaitAsync(TimeSpan.FromSeconds(20)); + }); + } + + private static async Task CountRowsAsync(ArrowBatchReader reader) + { + long rows = 0; + RecordBatch? batch; + while ((batch = await reader.ReadNextRecordBatchAsync()) is not null) + { + rows += batch.Length; + } + + return rows; + } +}