diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index dc54faf0..04b11a10 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -84,6 +84,33 @@ jobs: shell: bash run: ci/scripts/test.sh $(pwd) + go-interop: + name: arrow-go interop ${{ matrix.runs-on }} + runs-on: ${{ matrix.runs-on }} + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + runs-on: + - macos-latest + - ubuntu-latest + - windows-latest + steps: + - name: Setup .NET + uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6.1.0 + with: + dotnet-version: 8.0.x + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Setup Go + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: test/arrow-go-interop/go.mod + cache-dependency-path: test/arrow-go-interop/go.sum + - name: Test + shell: bash + run: ci/scripts/test_go_interop.sh $(pwd) + integration: name: Integration runs-on: ubuntu-latest diff --git a/ci/scripts/build_go_interop.sh b/ci/scripts/build_go_interop.sh new file mode 100755 index 00000000..a967d1c4 --- /dev/null +++ b/ci/scripts/build_go_interop.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# +# 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. + +# Builds the arrow-go interop shim (test/arrow-go-interop) as a C shared +# library and prints its path. Requires Go and a C compiler for cgo (on +# Windows, MinGW-w64 gcc). +# +# Usage: build_go_interop.sh [output_dir] +# +# Point the tests at the result with: +# export ARROW_GO_INTEROP_LIB=$(ci/scripts/build_go_interop.sh .) + +set -euo pipefail + +source_dir=$(cd "${1}" && pwd) +output_dir=${2:-${source_dir}/artifacts/arrow-go-interop} + +case "$(uname -s)" in +Linux*) library_name=libarrow_go_interop.so ;; +Darwin*) library_name=libarrow_go_interop.dylib ;; +MINGW* | MSYS* | CYGWIN*) library_name=arrow_go_interop.dll ;; +*) + echo "Unsupported platform: $(uname -s)" >&2 + exit 1 + ;; +esac + +mkdir -p "${output_dir}" +output_dir=$(cd "${output_dir}" && pwd) + +CGO_ENABLED=1 go build \ + -C "${source_dir}/test/arrow-go-interop" \ + -buildmode=c-shared \ + -o "${output_dir}/${library_name}" \ + . >&2 + +echo "${output_dir}/${library_name}" diff --git a/ci/scripts/test_go_interop.sh b/ci/scripts/test_go_interop.sh new file mode 100755 index 00000000..a166c8a8 --- /dev/null +++ b/ci/scripts/test_go_interop.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# +# 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. + +# Builds the arrow-go interop shim and runs the C Async Device Stream interop +# tests against it. Requires Go and a C compiler for cgo. +# +# Usage: test_go_interop.sh + +set -euo pipefail + +source_dir=$(cd "${1}" && pwd) + +# Paths handed to .NET and Go must be native paths on Windows. +native_path() { + if type cygpath >/dev/null 2>&1; then + cygpath -m "${1}" + else + echo "${1}" + fi +} + +echo "::group::Toolchain" +go version +go env CC CGO_ENABLED +cc_name=$(go env CC) +if type "${cc_name}" >/dev/null 2>&1; then + "${cc_name}" --version +else + echo "C compiler '${cc_name}' (needed by cgo) was not found on PATH" >&2 +fi +echo "::endgroup::" + +echo "::group::Build arrow-go interop shim" +library=$(bash "${source_dir}/ci/scripts/build_go_interop.sh" "${source_dir}") +echo "::endgroup::" + +ARROW_GO_INTEROP_LIB=$(native_path "${library}") +ARROW_GO_INTEROP_REQUIRED=1 +# The test host swallows stderr, so have Go write fatal errors here instead. +crash_log="$(dirname "${library}")/go-crash.log" +rm -f "${crash_log}" +ARROW_GO_INTEROP_CRASH_LOG=$(native_path "${crash_log}") +export ARROW_GO_INTEROP_LIB ARROW_GO_INTEROP_REQUIRED ARROW_GO_INTEROP_CRASH_LOG + +status=0 +dotnet test "${source_dir}/test/Apache.Arrow.Tests" \ + --framework net8.0 \ + --filter "FullyQualifiedName~CAsyncDeviceStreamGoInteropTests" || + status=$? + +if [ -s "${crash_log}" ]; then + echo "Go runtime crash output:" >&2 + cat "${crash_log}" >&2 +fi + +exit "${status}" diff --git a/dev/release/rat_exclude_files.txt b/dev/release/rat_exclude_files.txt index 14a5af7e..d452f676 100644 --- a/dev/release/rat_exclude_files.txt +++ b/dev/release/rat_exclude_files.txt @@ -19,6 +19,7 @@ *.resx *.sln *.slnf +test/arrow-go-interop/go.sum .github/pull_request_template.md src/Apache.Arrow/Flatbuf/* docs/images/*.png diff --git a/src/Apache.Arrow/C/CArrowAsyncDeviceStreamConsumer.cs b/src/Apache.Arrow/C/CArrowAsyncDeviceStreamConsumer.cs new file mode 100644 index 00000000..aab84e14 --- /dev/null +++ b/src/Apache.Arrow/C/CArrowAsyncDeviceStreamConsumer.cs @@ -0,0 +1,641 @@ +// 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; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; +using System.Threading; +using System.Threading.Tasks; +using Apache.Arrow.Ipc; + +namespace Apache.Arrow.C +{ + /// + /// Consumes data from an async device stream producer by providing an + /// . Returns an + /// that yields the received batches. + /// + [Experimental("ArrowAsyncDeviceStreamApi")] + public static class CArrowAsyncDeviceStreamConsumer + { + /// + /// The default number of batches the consumer keeps requested ahead of the reader. + /// + public const long DefaultQueueSize = 16; + + private const int EOTHER = 131; + +#if NET5_0_OR_GREATER + private static unsafe delegate* unmanaged OnSchemaPtr => &OnSchema; + private static unsafe delegate* unmanaged OnNextTaskPtr => &OnNextTask; + private static unsafe delegate* unmanaged OnErrorPtr => &OnError; + private static unsafe delegate* unmanaged ReleasePtr => &Release; +#else + internal unsafe delegate int OnSchemaDelegate(CArrowAsyncDeviceStreamHandler* handler, CArrowSchema* schema); + private static unsafe readonly NativeDelegate s_onSchema = new NativeDelegate(OnSchema); + private static unsafe IntPtr OnSchemaPtr => s_onSchema.Pointer; + internal unsafe delegate int OnNextTaskDelegate(CArrowAsyncDeviceStreamHandler* handler, CArrowAsyncTask* task, byte* metadata); + private static unsafe readonly NativeDelegate s_onNextTask = new NativeDelegate(OnNextTask); + private static unsafe IntPtr OnNextTaskPtr => s_onNextTask.Pointer; + internal unsafe delegate void OnErrorDelegate(CArrowAsyncDeviceStreamHandler* handler, int code, byte* message, byte* metadata); + private static unsafe readonly NativeDelegate s_onError = new NativeDelegate(OnError); + private static unsafe IntPtr OnErrorPtr => s_onError.Pointer; + internal unsafe delegate void ReleaseHandlerDelegate(CArrowAsyncDeviceStreamHandler* handler); + private static unsafe readonly NativeDelegate s_release = new NativeDelegate(Release); + private static unsafe IntPtr ReleasePtr => s_release.Pointer; +#endif + + /// + /// Create a consumer handler and return an + /// that will yield batches pushed by the producer. + /// + /// + /// + /// The caller must pass to a producer. The producer + /// populates the handler's producer field and calls on_schema; the consumer + /// then requests batches and requests more as + /// the reader consumes them, so at most about that many batches are buffered. + /// + /// + /// The consumer owns the handler's memory and frees it when the producer + /// calls the handler's release callback, so the caller must not free it and + /// must not use the pointer after handing it to the producer. A handler that + /// is never handed to a producer is never released, and leaks. + /// + /// + /// Disposing the returned stream before the end cancels the producer, which + /// may release the handler some time later. + /// + /// + /// + /// + /// IArrowArrayStream stream = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + /// foreign_produce_function(handler); + /// RecordBatch batch = await stream.ReadNextRecordBatchAsync(); + /// + /// + /// Receives the newly allocated handler to pass to a producer. + /// The number of batches to keep requested ahead of the reader. + /// An IArrowArrayStream that yields the received batches. + public static unsafe IArrowArrayStream CreateStream(out CArrowAsyncDeviceStreamHandler* handler, long queueSize = DefaultQueueSize) + { + if (queueSize <= 0) + { + throw new ArgumentOutOfRangeException(nameof(queueSize), queueSize, "The queue size must be positive."); + } + + CArrowAsyncDeviceStreamHandler* newHandler = CArrowAsyncDeviceStreamHandler.Create(); + var state = new ConsumerState(newHandler, queueSize); + + newHandler->on_schema = OnSchemaPtr; + newHandler->on_next_task = OnNextTaskPtr; + newHandler->on_error = OnErrorPtr; + newHandler->release = ReleasePtr; + + GCHandle gch = GCHandle.Alloc(state); + newHandler->private_data = (void*)GCHandle.ToIntPtr(gch); + + handler = newHandler; + return state; + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static int OnSchema(CArrowAsyncDeviceStreamHandler* handler, CArrowSchema* schema) + { + ConsumerState state = null; + try + { + state = ConsumerState.FromPointer(handler->private_data); + Schema importedSchema = CArrowSchemaImporter.ImportSchema(schema); + state.SetSchema(importedSchema); + + // Calling request() synchronously from on_schema is explicitly allowed. + state.StartRequesting(); + return 0; + } + catch (Exception ex) + { + // After a failed on_schema the producer only calls release, so record + // the failure here or the reader would just see an empty stream. + state?.SignalError(ex); + return EOTHER; + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static int OnNextTask(CArrowAsyncDeviceStreamHandler* handler, CArrowAsyncTask* task, byte* metadata) + { + try + { + var state = ConsumerState.FromPointer(handler->private_data); + + if (task == null) + { + // End of stream + state.SignalComplete(); + return 0; + } + + // The task is only valid during this call, so extract it now. Even an + // unwanted task must be extracted so the producer can clean up. An + // output array is always passed, even though the spec allows NULL, + // because not every producer handles NULL (arrow-go v18.8.0 doesn't). + CArrowDeviceArray cDeviceArray = new CArrowDeviceArray(); +#if NET5_0_OR_GREATER + int errno = task->extract_data(task, &cDeviceArray); +#else + int errno = NativeDelegate.GetDelegateForFunctionPointer(task->extract_data)(task, &cDeviceArray); +#endif + if (errno != 0) + { + // Record the failure here rather than relying on the producer's + // on_error: it can't always send one (e.g. if it has already + // finished), and without it the batch would be silently lost. + // Returning non-zero also tells the producer to stop and release. + state.SignalError(new Exception($"Failed to extract data from an async task. Error code: {errno}")); + return errno; + } + + if (cDeviceArray.array.release == default) + { + return 0; + } + + if (state.IsDisposed) + { + // Cancelled; drop any batches still in flight. + ReleaseArray(&cDeviceArray.array); + return 0; + } + + RecordBatch batch; + try + { + batch = CArrowDeviceArrayImporter.ImportRecordBatch(&cDeviceArray, state.Schema); + } + catch (Exception ex) + { + ReleaseArray(&cDeviceArray.array); + state.SignalError(ex); + return EOTHER; + } + + state.EnqueueBatch(batch); + return 0; + } + catch (Exception) + { + return EOTHER; + } + } + + private unsafe static void ReleaseArray(CArrowArray* array) + { + if (array->release != default) + { +#if NET5_0_OR_GREATER + array->release(array); +#else + NativeDelegate.GetDelegateForFunctionPointer(array->release)(array); +#endif + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static void OnError(CArrowAsyncDeviceStreamHandler* handler, int code, byte* message, byte* metadata) + { + try + { + var state = ConsumerState.FromPointer(handler->private_data); + string msg = message != null ? StringUtil.PtrToStringUtf8(message) : $"Async stream error. Code: {code}"; + state.SignalError(new Exception(msg)); + } + catch (Exception) + { + // Cannot propagate errors from on_error + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static void Release(CArrowAsyncDeviceStreamHandler* handler) + { + try + { + GCHandle gch = GCHandle.FromIntPtr((IntPtr)handler->private_data); + var state = (ConsumerState)gch.Target; + + // After this, the state no longer touches the handler. + state.SignalReleased(); + gch.Free(); + } + catch (Exception) + { + // Cannot propagate errors from release + } + + // release is the last call the producer makes on the handler, and the + // consumer allocated it in CreateStream, so it can be freed here. + CArrowAsyncDeviceStreamHandler.Free(handler); + } + + private sealed unsafe class ConsumerState : IArrowArrayStream + { + private readonly CArrowAsyncDeviceStreamHandler* _handler; + private readonly long _replenishThreshold; + + // Guards the batch queue and waiters. + private readonly object _gate = new object(); + private readonly Queue _buffered = new Queue(); + private readonly Queue _waiters = new Queue(); + private readonly TaskCompletionSource _schemaReady; + private bool _completed; + private Exception _error; + private long _consumedSinceRequest; + + // Guards every use of the handler and producer structs: the handler is + // freed in release, and the producer may free its struct as soon as + // release returns. Held while calling request/cancel, so release + // (which takes it too) can't complete in the middle of one. + // + // Holding it across those calls is deliberate. The spec only keeps the + // producer valid until release, so the consumer must keep release from + // completing while it's calling into the producer; releasing the lock + // before the call would let the producer free the struct the call uses. + // A producer that calls release synchronously from cancel is fine: it + // runs on the same thread, and monitors are reentrant. A producer whose + // cancel blocks until another thread has called release would deadlock + // with any consumer that does this. + // + // Separate from _gate so a producer that blocks in request() while + // delivering a batch can't deadlock against EnqueueBatch. + private readonly object _producerGate = new object(); + private bool _released; + private bool _cancelled; + private bool _cancelSent; + + private volatile bool _disposed; + + public ConsumerState(CArrowAsyncDeviceStreamHandler* handler, long queueSize) + { + _handler = handler; + QueueSize = queueSize; + // Re-request in chunks rather than one batch at a time, so the + // producer sees fewer request() calls. + _replenishThreshold = Math.Max(1, queueSize / 2); + _schemaReady = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + } + + public long QueueSize { get; } + + public bool IsDisposed => _disposed; + + public Schema Schema + { + get + { + // Block until schema is available + return _schemaReady.Task.GetAwaiter().GetResult(); + } + } + + public static ConsumerState FromPointer(void* ptr) + { + GCHandle gch = GCHandle.FromIntPtr((IntPtr)ptr); + return (ConsumerState)gch.Target; + } + + public void SetSchema(Schema schema) + { + _schemaReady.TrySetResult(schema); + } + + /// + /// Called from on_schema, once the producer is attached: make the initial + /// request, or, if the stream was disposed before a producer attached, send + /// the cancellation that couldn't be sent then. Otherwise the producer would + /// get neither demand nor cancel and never release the handler. + /// + public void StartRequesting() + { + lock (_producerGate) + { + CArrowAsyncProducer* producer = _handler->producer; + if (_released || producer == null) + { + return; + } + + if (_cancelled) + { + if (!_cancelSent) + { + _cancelSent = true; +#if NET5_0_OR_GREATER + producer->cancel(producer); +#else + NativeDelegate.GetDelegateForFunctionPointer(producer->cancel)(producer); +#endif + } + return; + } + +#if NET5_0_OR_GREATER + producer->request(producer, QueueSize); +#else + NativeDelegate.GetDelegateForFunctionPointer(producer->request)(producer, QueueSize); +#endif + } + } + + public void RequestFromProducer(long n) + { + lock (_producerGate) + { + if (_released || _cancelled || _handler->producer == null) + { + return; + } + + CArrowAsyncProducer* producer = _handler->producer; +#if NET5_0_OR_GREATER + producer->request(producer, n); +#else + NativeDelegate.GetDelegateForFunctionPointer(producer->request)(producer, n); +#endif + } + } + + private void CancelProducer() + { + lock (_producerGate) + { + if (_released || _cancelled) + { + return; + } + _cancelled = true; + + CArrowAsyncProducer* producer = _handler->producer; + if (producer == null) + { + // No producer attached yet; StartRequesting sends the cancel + // once one is. + return; + } + + _cancelSent = true; +#if NET5_0_OR_GREATER + producer->cancel(producer); +#else + NativeDelegate.GetDelegateForFunctionPointer(producer->cancel)(producer); +#endif + } + } + + /// + /// Called whenever a batch is handed to the reader; asks the producer for + /// more once enough of the queue has drained. + /// + private void OnBatchConsumed() + { + long toRequest = 0; + lock (_gate) + { + if (++_consumedSinceRequest >= _replenishThreshold) + { + toRequest = _consumedSinceRequest; + _consumedSinceRequest = 0; + } + } + + if (toRequest > 0) + { + RequestFromProducer(toRequest); + } + } + + public void EnqueueBatch(RecordBatch batch) + { + Waiter waiter = null; + bool rejected = false; + lock (_gate) + { + // Dispose sets _disposed before it drains the queue under this + // lock, so a batch either gets drained or is rejected here. + if (_disposed) + { + rejected = true; + } + else + { + // Skip waiters whose read was cancelled; handing the batch to + // one of them would lose it. + while (_waiters.Count > 0) + { + Waiter candidate = _waiters.Dequeue(); + if (candidate.Completion.TrySetResult(batch)) + { + waiter = candidate; + break; + } + } + + if (waiter == null) + { + _buffered.Enqueue(batch); + } + } + } + + if (rejected) + { + batch.Dispose(); + return; + } + + if (waiter != null) + { + waiter.Registration.Dispose(); + // request() may be called synchronously from on_next_task. + OnBatchConsumed(); + } + } + + public void SignalComplete() + { + List waiters; + lock (_gate) + { + _completed = true; + waiters = DrainWaiters(); + } + foreach (Waiter waiter in waiters) + { + waiter.Completion.TrySetResult(null); + waiter.Registration.Dispose(); + } + } + + public void SignalError(Exception ex) + { + List waiters; + lock (_gate) + { + if (_error == null) + { + _error = ex; + } + _completed = true; + _schemaReady.TrySetException(ex); + waiters = DrainWaiters(); + } + foreach (Waiter waiter in waiters) + { + waiter.Completion.TrySetException(ex); + waiter.Registration.Dispose(); + } + } + + public void SignalReleased() + { + lock (_producerGate) + { + // After this, the producer struct may be freed at any time. + _released = true; + } + + // Don't leave Schema blocking forever if the producer released + // the handler without ever delivering a schema. + _schemaReady.TrySetException(new InvalidOperationException( + "The async stream was released before a schema was received.")); + SignalComplete(); + } + + private List DrainWaiters() + { + var waiters = new List(_waiters); + _waiters.Clear(); + return waiters; + } + + public ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + if (_disposed) + { + throw new ObjectDisposedException(nameof(ConsumerState)); + } + + if (cancellationToken.IsCancellationRequested) + { + return new ValueTask(Task.FromCanceled(cancellationToken)); + } + + RecordBatch buffered = null; + lock (_gate) + { + // Check again under the lock: Dispose may have drained the queue + // and the waiters since the check above, and a waiter added now + // would never be completed. + if (_disposed) + { + return new ValueTask(Task.FromException( + new ObjectDisposedException(nameof(ConsumerState)))); + } + + if (_buffered.Count > 0) + { + buffered = _buffered.Dequeue(); + } + else if (_error != null) + { + return new ValueTask(Task.FromException(_error)); + } + else if (_completed) + { + return new ValueTask((RecordBatch)null); + } + else + { + var waiter = new Waiter(); + if (cancellationToken.CanBeCanceled) + { + // The callback doesn't take _gate: a cancelled waiter is + // simply skipped when the next batch arrives. This also keeps + // Registration.Dispose (which waits for a running callback) + // from deadlocking against the lock. + waiter.Registration = cancellationToken.Register( + () => waiter.Completion.TrySetCanceled(cancellationToken)); + } + _waiters.Enqueue(waiter); + return new ValueTask(waiter.Completion.Task); + } + } + + OnBatchConsumed(); + return new ValueTask(buffered); + } + + public void Dispose() + { + if (_disposed) + { + return; + } + _disposed = true; + + // If the producer is still active, ask it to stop. It may keep + // delivering for a while; OnNextTask drops those batches. + CancelProducer(); + + List buffered; + List waiters; + lock (_gate) + { + buffered = new List(_buffered); + _buffered.Clear(); + waiters = DrainWaiters(); + } + foreach (RecordBatch batch in buffered) + { + batch.Dispose(); + } + + // Don't leave a read that's still waiting hanging forever. + var disposedException = new ObjectDisposedException(nameof(ConsumerState)); + foreach (Waiter waiter in waiters) + { + waiter.Completion.TrySetException(disposedException); + waiter.Registration.Dispose(); + } + } + + private sealed class Waiter + { + public readonly TaskCompletionSource Completion = + new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + public CancellationTokenRegistration Registration; + } + } + } +} diff --git a/src/Apache.Arrow/C/CArrowAsyncDeviceStreamHandler.cs b/src/Apache.Arrow/C/CArrowAsyncDeviceStreamHandler.cs new file mode 100644 index 00000000..86d1127d --- /dev/null +++ b/src/Apache.Arrow/C/CArrowAsyncDeviceStreamHandler.cs @@ -0,0 +1,112 @@ +// 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; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; + +namespace Apache.Arrow.C +{ + /// + /// An Arrow C Async Device Stream Interface ArrowAsyncDeviceStreamHandler, which + /// is created by the consumer to receive pushed data from a producer. + /// + /// + /// This matches the layout of the ArrowAsyncDeviceStreamHandler struct described in + /// https://arrow.apache.org/docs/format/CDeviceDataInterface.html. + /// + [StructLayout(LayoutKind.Sequential)] + [Experimental("ArrowAsyncDeviceStreamApi")] + public unsafe struct CArrowAsyncDeviceStreamHandler + { + /// + /// Callback invoked by the producer to deliver the stream schema. + /// Called once before any on_next_task calls. + /// + /// Return value: 0 if successful, an errno-compatible error code otherwise. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged on_schema; +#else + internal IntPtr on_schema; +#endif + + /// + /// Callback invoked by the producer to deliver a data batch. + /// A null task pointer signals end-of-stream. + /// + /// Return value: 0 if successful, an errno-compatible error code otherwise. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged on_next_task; +#else + internal IntPtr on_next_task; +#endif + + /// + /// Callback invoked by the producer when an error occurs. + /// The producer must still call release after calling on_error. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged on_error; +#else + internal IntPtr on_error; +#endif + + /// + /// Release callback: release the handler's own resources. + /// Called exactly once by the producer after all other callbacks. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged release; +#else + internal IntPtr release; +#endif + + /// + /// Pointer to the ArrowAsyncProducer. Populated by the producer before + /// calling on_schema. Provides flow control via request() and cancel(). + /// + public CArrowAsyncProducer* producer; + + public void* private_data; + + /// + /// Allocate and zero-initialize an unmanaged pointer of this type. + /// + /// + /// This pointer must later be freed by . + /// + public static CArrowAsyncDeviceStreamHandler* Create() + { + var ptr = (CArrowAsyncDeviceStreamHandler*)Marshal.AllocHGlobal(sizeof(CArrowAsyncDeviceStreamHandler)); + + *ptr = default; + + return ptr; + } + + /// + /// Free a pointer that was allocated in . + /// + /// + /// Do not call this on a pointer that was allocated elsewhere. + /// + public static void Free(CArrowAsyncDeviceStreamHandler* handler) + { + Marshal.FreeHGlobal((IntPtr)handler); + } + } +} diff --git a/src/Apache.Arrow/C/CArrowAsyncDeviceStreamProducer.cs b/src/Apache.Arrow/C/CArrowAsyncDeviceStreamProducer.cs new file mode 100644 index 00000000..47a9d8e7 --- /dev/null +++ b/src/Apache.Arrow/C/CArrowAsyncDeviceStreamProducer.cs @@ -0,0 +1,713 @@ +// 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; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; +using System.Threading; +using System.Threading.Tasks; +using Apache.Arrow.Ipc; + +namespace Apache.Arrow.C +{ + /// + /// Produces data from an by pushing it through + /// an . + /// + [Experimental("ArrowAsyncDeviceStreamApi")] + public static class CArrowAsyncDeviceStreamProducer + { + private const int EINVAL = 22; + private const int EOTHER = 131; + +#if NET5_0_OR_GREATER + private static unsafe delegate* unmanaged RequestPtr => &OnRequest; + private static unsafe delegate* unmanaged CancelPtr => &OnCancel; + private static unsafe delegate* unmanaged ExtractDataPtr => &ExtractData; +#else + internal unsafe delegate void RequestDelegate(CArrowAsyncProducer* producer, long n); + private static unsafe readonly NativeDelegate s_request = new NativeDelegate(OnRequest); + private static unsafe IntPtr RequestPtr => s_request.Pointer; + internal unsafe delegate void CancelDelegate(CArrowAsyncProducer* producer); + private static unsafe readonly NativeDelegate s_cancel = new NativeDelegate(OnCancel); + private static unsafe IntPtr CancelPtr => s_cancel.Pointer; + internal unsafe delegate int ExtractDataDelegate(CArrowAsyncTask* task, CArrowDeviceArray* deviceArray); + private static unsafe readonly NativeDelegate s_extractData = new NativeDelegate(ExtractData); + private static unsafe IntPtr ExtractDataPtr => s_extractData.Pointer; +#endif + + /// + /// Produce data from an by pushing it through + /// the provided handler. The producer populates the handler's producer field + /// and calls on_schema before this method returns; batches are then delivered + /// asynchronously as the consumer requests them. + /// + /// + /// Handler callbacks are never invoked concurrently, and the handler's release + /// callback is called exactly once, as the last call on the handler. The + /// source stream is disposed after release. As with the C stream exporters, + /// the producer takes ownership of each batch the source returns and disposes + /// it once the consumer has released (or declined) the exported data. + /// + /// The source stream to produce from. + /// The consumer-allocated handler to push data through. + public static unsafe void Produce(IArrowArrayStream arrayStream, CArrowAsyncDeviceStreamHandler* handler) + { + if (arrayStream == null) + { + throw new ArgumentNullException(nameof(arrayStream)); + } + if (handler == null) + { + throw new ArgumentNullException(nameof(handler)); + } + + var state = new ProducerState(arrayStream, handler); + state.Start(); + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static void OnRequest(CArrowAsyncProducer* producer, long n) + { + // Exceptions must not escape an unmanaged callback. request() has no + // return value; errors it detects are reported later via on_error. + try + { + var state = ProducerState.FromPointer(producer->private_data); + state.Request(n); + } + catch (Exception) + { + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static void OnCancel(CArrowAsyncProducer* producer) + { + // Exceptions must not escape an unmanaged callback. + try + { + var state = ProducerState.FromPointer(producer->private_data); + state.Cancel(); + } + catch (Exception) + { + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private unsafe static int ExtractData(CArrowAsyncTask* task, CArrowDeviceArray* deviceArray) + { + // Consumers may extract after the producer has finished and released + // the handler (arrow-go does), so this must only depend on the task. + TaskState taskState = null; + try + { + // extract_data is called exactly once per task, so the task's + // GCHandle is always freed here. Clearing private_data makes an + // erroneous second call fail cleanly instead of touching a freed handle. + GCHandle gch = GCHandle.FromIntPtr((IntPtr)task->private_data); + task->private_data = null; + try + { + taskState = (TaskState)gch.Target; + if (deviceArray != null) + { + // Like the C stream exporters, take over the source stream's + // reference: the exported array disposes the batch when released + // (or right away if the export fails). + CArrowDeviceArrayExporter.ExportRecordBatch(taskState.Batch, deviceArray, transferOwnership: true); + } + else + { + // The consumer doesn't want the data. + taskState.Batch.Dispose(); + } + return 0; + } + finally + { + gch.Free(); + } + } + catch (Exception ex) + { + // The spec says a failed extract_data is followed by on_error. + taskState?.Producer.ReportError(EOTHER, ex.Message); + return EOTHER; + } + } + + /// + /// What the produce loop should do next. + /// + private enum Step + { + /// No demand: the loop exits until the next request(). + Idle, + /// Read a batch from the source and deliver it. + Produce, + /// Report a pending error, then release. + Error, + /// Cancelled: release without further callbacks. + Release, + } + + /// + /// State for one produced stream. + /// + /// + /// All handler callbacks after on_schema are made from a single produce loop, + /// and at most one loop runs at a time (), so callbacks + /// are never concurrent. request() and cancel() only update state under + /// and start the loop if it isn't running; they never call + /// back into the handler themselves, as the spec requires. + /// + private sealed unsafe class ProducerState + { + private readonly IArrowArrayStream _arrayStream; + private readonly CArrowAsyncDeviceStreamHandler* _handler; + private CArrowAsyncProducer* _producer; + + private readonly object _gate = new object(); + private long _demand; + private bool _schemaDelivered; + private bool _running; + private bool _cancelled; + // Set once the loop has committed to its final callbacks (end of stream, + // on_error or release); later request/cancel/errors are ignored, so a + // decision made under _gate can't be overtaken. + private bool _completing; + private bool _finished; + private bool _hasPendingError; + private int _pendingErrorCode; + private string _pendingErrorMessage; + + // Cancelled by cancel() so a source read that's waiting for input wakes + // up. Never disposed: it has no timer, and a late Cancel() must not throw. + private readonly CancellationTokenSource _cancellation = new CancellationTokenSource(); + + public ProducerState(IArrowArrayStream arrayStream, CArrowAsyncDeviceStreamHandler* handler) + { + _arrayStream = arrayStream; + _handler = handler; + } + + public IArrowArrayStream ArrayStream => _arrayStream; + + public CancellationToken CancellationToken => _cancellation.Token; + + public static ProducerState FromPointer(void* ptr) + { + GCHandle gch = GCHandle.FromIntPtr((IntPtr)ptr); + return (ProducerState)gch.Target; + } + + public void Start() + { + // Allocate and populate the producer struct + _producer = CArrowAsyncProducer.Create(); + _producer->device_type = ArrowDeviceType.Cpu; + _producer->request = RequestPtr; + _producer->cancel = CancelPtr; + _producer->additional_metadata = null; + + GCHandle gch = GCHandle.Alloc(this); + _producer->private_data = (void*)GCHandle.ToIntPtr(gch); + + // Set the producer on the handler before calling on_schema + _handler->producer = _producer; + + // Deliver the schema. If it can't be exported, the consumer still + // has to hear about it: on_error followed by release. + CArrowSchema cSchema = new CArrowSchema(); + try + { + CArrowSchemaExporter.ExportSchema(_arrayStream.Schema, &cSchema); + } + catch (Exception ex) + { + FailWithError(EOTHER, ex.Message); + return; + } + + // The consumer may call request() or cancel() from within on_schema. + // That only records state: the loop doesn't start until on_schema + // has returned, so on_next_task can't overlap it. +#if NET5_0_OR_GREATER + int errno = _handler->on_schema(_handler, &cSchema); +#else + int errno = NativeDelegate.GetDelegateForFunctionPointer(_handler->on_schema)(_handler, &cSchema); +#endif + + // A consumer that fails may not have taken ownership of the schema. + if (cSchema.release != default) + { +#if NET5_0_OR_GREATER + cSchema.release(&cSchema); +#else + NativeDelegate.GetDelegateForFunctionPointer(cSchema.release)(&cSchema); +#endif + } + + if (errno != 0) + { + // Per the spec: no on_error after a failed on_schema, just release. + Finish(); + return; + } + + bool startLoop; + lock (_gate) + { + _schemaDelivered = true; + startLoop = TryClaimLoopLocked(); + } + if (startLoop) + { + StartLoop(); + } + } + + public void Request(long n) + { + bool startLoop; + lock (_gate) + { + // After cancel, request must be a no-op. + if (_cancelled || _completing || _finished) + { + return; + } + + if (n <= 0) + { + SetPendingErrorLocked(EINVAL, $"request() called with invalid n = {n}; n must be positive."); + } + else + { + _demand = n > long.MaxValue - _demand ? long.MaxValue : _demand + n; + } + + startLoop = TryClaimLoopLocked(); + } + if (startLoop) + { + StartLoop(); + } + } + + public void Cancel() + { + bool startLoop; + lock (_gate) + { + // cancel must be idempotent. + if (_cancelled || _completing || _finished) + { + return; + } + + _cancelled = true; + startLoop = TryClaimLoopLocked(); + } + if (startLoop) + { + StartLoop(); + } + + // Wake a source read that's waiting for input. Done on the thread pool + // because cancelling can run the read's continuation inline, and that + // would call release from inside the consumer's call to cancel(). + Task.Run(() => + { + try + { + _cancellation.Cancel(); + } + catch (Exception) + { + // A source's cancellation callback threw; the loop will still + // see _cancelled and release. + } + }); + } + + /// + /// Report an error to the consumer from outside the produce loop + /// (currently, a failed extract_data). Ignored once the stream is done. + /// + public void ReportError(int code, string message) + { + bool startLoop; + lock (_gate) + { + // Too late to report: nothing may follow release, and an on_error + // after end-of-stream would contradict it. Consumers may extract + // after either (arrow-go does), so they can't rely on on_error for + // a failed extract; extract_data's return value tells them. + if (_completing || _finished) + { + return; + } + + SetPendingErrorLocked(code, message); + startLoop = TryClaimLoopLocked(); + } + if (startLoop) + { + StartLoop(); + } + } + + private void SetPendingErrorLocked(int code, string message) + { + if (!_hasPendingError) + { + _hasPendingError = true; + _pendingErrorCode = code; + _pendingErrorMessage = message; + } + } + + /// + /// Returns true if the caller should start the produce loop, in which case + /// has been set and the caller owns starting it. + /// + private bool TryClaimLoopLocked() + { + if (_running || _finished || !_schemaDelivered) + { + return false; + } + + if (_cancelled || _hasPendingError || _demand > 0) + { + _running = true; + return true; + } + + return false; + } + + private void StartLoop() + { + // A separate task keeps request() from ever calling back into the + // handler synchronously. + Task.Run(() => RunProduceLoopAsync(this)); + } + + /// + /// Decide the loop's next step. When there's nothing to do, this marks + /// the loop as stopped under the same lock that request() takes, so a + /// concurrent request() either is seen here or starts a new loop. + /// + public Step TakeNextStep(out int errorCode, out string errorMessage) + { + errorCode = 0; + errorMessage = null; + lock (_gate) + { + Step step = TakeTerminalStepLocked(out errorCode, out errorMessage); + if (step != Step.Produce) + { + return step; + } + + if (_demand == 0) + { + _running = false; + return Step.Idle; + } + + _demand--; + return Step.Produce; + } + } + + /// + /// If a pending error or cancellation must end the stream, commit to that + /// (setting ) and return the step; otherwise + /// return . A pending error wins over cancel. + /// + private Step TakeTerminalStepLocked(out int errorCode, out string errorMessage) + { + errorCode = 0; + errorMessage = null; + + if (_hasPendingError) + { + _completing = true; + errorCode = _pendingErrorCode; + errorMessage = _pendingErrorMessage; + return Step.Error; + } + + if (_cancelled) + { + _completing = true; + return Step.Release; + } + + return Step.Produce; + } + + /// + /// Handle the result of a source read: deliver the batch, or end the + /// stream. Errors or cancellation that arrived while the read was in + /// progress take precedence. Returns false if the stream is now finished. + /// Separated from the async loop because unsafe pointer operations + /// cannot appear in async methods. + /// + public bool DeliverBatch(RecordBatch batch) + { + Step step; + int errorCode; + string errorMessage; + lock (_gate) + { + step = TakeTerminalStepLocked(out errorCode, out errorMessage); + if (step == Step.Produce && batch == null) + { + _completing = true; + } + } + + switch (step) + { + case Step.Error: + batch?.Dispose(); + FailWithError(errorCode, errorMessage); + return false; + case Step.Release: + // Cancelled while reading: drop the batch and just release. + batch?.Dispose(); + Finish(); + return false; + } + + if (batch == null) + { + SignalEndOfStream(); + Finish(); + return false; + } + + var taskState = new TaskState(this, batch); + GCHandle taskGch = GCHandle.Alloc(taskState); + CArrowAsyncTask cTask = new CArrowAsyncTask(); + cTask.extract_data = ExtractDataPtr; + cTask.private_data = (void*)GCHandle.ToIntPtr(taskGch); + +#if NET5_0_OR_GREATER + int errno = _handler->on_next_task(_handler, &cTask, null); +#else + int errno = NativeDelegate.GetDelegateForFunctionPointer(_handler->on_next_task)(_handler, &cTask, null); +#endif + if (errno != 0) + { + // Per the spec: no on_error after a failed on_next_task, just release. + // The task's GCHandle can't be freed safely here: the consumer may + // have extracted from a copy of the task, which already freed it. + Finish(); + return false; + } + + return true; + } + + /// + /// Handle a source read that threw. If the stream was cancelled meanwhile + /// (including by our own cancellation token), just release; a pending + /// error is reported in preference to the read's own exception. + /// + public void HandleReadFailure(Exception ex) + { + Step step; + int errorCode; + string errorMessage; + lock (_gate) + { + step = TakeTerminalStepLocked(out errorCode, out errorMessage); + _completing = true; + } + + switch (step) + { + case Step.Error: + FailWithError(errorCode, errorMessage); + break; + case Step.Release: + Finish(); + break; + default: + FailWithError(EOTHER, ex.Message); + break; + } + } + + public void FailWithError(int code, string message) + { + lock (_gate) + { + // Nothing may follow release. + if (_finished) + { + return; + } + } + + SignalError(code, message); + Finish(); + } + + private void SignalEndOfStream() + { +#if NET5_0_OR_GREATER + _handler->on_next_task(_handler, null, null); +#else + NativeDelegate.GetDelegateForFunctionPointer(_handler->on_next_task)(_handler, null, null); +#endif + } + + private void SignalError(int code, string message) + { + byte* msgPtr = null; + try + { + if (message != null) + { + msgPtr = StringUtil.ToCStringUtf8(message); + } +#if NET5_0_OR_GREATER + _handler->on_error(_handler, code, msgPtr, null); +#else + NativeDelegate.GetDelegateForFunctionPointer(_handler->on_error)(_handler, code, msgPtr, null); +#endif + } + finally + { + if (msgPtr != null) + { + Marshal.FreeHGlobal((IntPtr)msgPtr); + } + } + } + + /// + /// Release the handler and free the producer. Only called from Start or + /// the produce loop, never concurrently, and at most once. + /// + public void Finish() + { + lock (_gate) + { + if (_finished) + { + return; + } + _finished = true; + } + +#if NET5_0_OR_GREATER + _handler->release(_handler); +#else + NativeDelegate.GetDelegateForFunctionPointer(_handler->release)(_handler); +#endif + + // The spec only requires the producer struct to stay valid until + // release is called, so it can be freed now. + GCHandle gch = GCHandle.FromIntPtr((IntPtr)_producer->private_data); + gch.Free(); + CArrowAsyncProducer.Free(_producer); + _producer = null; + + _arrayStream.Dispose(); + } + } + + /// + /// The produce loop, kept outside ProducerState so that it is not in an + /// unsafe context (await is not allowed in unsafe contexts). + /// + private static async Task RunProduceLoopAsync(ProducerState state) + { + try + { + while (true) + { + switch (state.TakeNextStep(out int errorCode, out string errorMessage)) + { + case Step.Idle: + return; + case Step.Error: + state.FailWithError(errorCode, errorMessage); + return; + case Step.Release: + state.Finish(); + return; + } + + RecordBatch batch; + try + { + batch = await state.ArrayStream.ReadNextRecordBatchAsync(state.CancellationToken).ConfigureAwait(false); + } + catch (Exception ex) + { + state.HandleReadFailure(ex); + return; + } + + if (!state.DeliverBatch(batch)) + { + return; + } + } + } + catch (Exception ex) + { + // Something unexpected (e.g. an exporter bug). Finish is idempotent, + // so this is safe even if the stream had already finished. + try + { + state.FailWithError(EOTHER, ex.Message); + } + catch (Exception) + { + } + } + } + + private sealed class TaskState + { + public TaskState(ProducerState producer, RecordBatch batch) + { + Producer = producer; + Batch = batch; + } + + public ProducerState Producer { get; } + + public RecordBatch Batch { get; } + } + } +} diff --git a/src/Apache.Arrow/C/CArrowAsyncProducer.cs b/src/Apache.Arrow/C/CArrowAsyncProducer.cs new file mode 100644 index 00000000..44c612ba --- /dev/null +++ b/src/Apache.Arrow/C/CArrowAsyncProducer.cs @@ -0,0 +1,93 @@ +// 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; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; + +namespace Apache.Arrow.C +{ + /// + /// An Arrow C Async Device Stream Interface ArrowAsyncProducer, which provides + /// flow control for the consumer to request data or cancel the stream. + /// + /// + /// This matches the layout of the ArrowAsyncProducer struct described in + /// https://arrow.apache.org/docs/format/CDeviceDataInterface.html. + /// + [StructLayout(LayoutKind.Sequential)] + [Experimental("ArrowAsyncDeviceStreamApi")] + public unsafe struct CArrowAsyncProducer + { + /// + /// The device type that this stream produces data on. + /// + public ArrowDeviceType device_type; + + /// + /// Callback for the consumer to request n additional data batches. + /// Must not synchronously call on_next_task or on_error to avoid recursion. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged request; +#else + internal IntPtr request; +#endif + + /// + /// Callback for the consumer to signal cancellation. + /// Must be idempotent and thread-safe. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged cancel; +#else + internal IntPtr cancel; +#endif + + /// + /// Optional stream-level metadata, encoded like Arrow schema metadata. + /// May be null. Must be valid for the lifetime of this object. + /// + public byte* additional_metadata; + + public void* private_data; + + /// + /// Allocate and zero-initialize an unmanaged pointer of this type. + /// + /// + /// This pointer must later be freed by . + /// + public static CArrowAsyncProducer* Create() + { + var ptr = (CArrowAsyncProducer*)Marshal.AllocHGlobal(sizeof(CArrowAsyncProducer)); + + *ptr = default; + + return ptr; + } + + /// + /// Free a pointer that was allocated in . + /// + /// + /// Do not call this on a pointer that was allocated elsewhere. + /// + public static void Free(CArrowAsyncProducer* producer) + { + Marshal.FreeHGlobal((IntPtr)producer); + } + } +} diff --git a/src/Apache.Arrow/C/CArrowAsyncTask.cs b/src/Apache.Arrow/C/CArrowAsyncTask.cs new file mode 100644 index 00000000..3e4cfeb3 --- /dev/null +++ b/src/Apache.Arrow/C/CArrowAsyncTask.cs @@ -0,0 +1,49 @@ +// 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; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; + +namespace Apache.Arrow.C +{ + /// + /// An Arrow C Async Device Stream Interface ArrowAsyncTask, which represents + /// a single data batch that can be extracted by the consumer. + /// + /// + /// This matches the layout of the ArrowAsyncTask struct described in + /// https://arrow.apache.org/docs/format/CDeviceDataInterface.html. + /// + [StructLayout(LayoutKind.Sequential)] + [Experimental("ArrowAsyncDeviceStreamApi")] + public unsafe struct CArrowAsyncTask + { + /// + /// Callback to extract the data for this task into an ArrowDeviceArray. + /// The consumer must call this even if it does not want the data (passing + /// a null out pointer is acceptable) so that the producer can clean up. + /// + /// Return value: 0 if successful, an errno-compatible error code otherwise. + /// +#if NET5_0_OR_GREATER + internal delegate* unmanaged extract_data; +#else + internal IntPtr extract_data; +#endif + + public void* private_data; + } +} diff --git a/test/Apache.Arrow.Tests/ArrowGoInteropFixture.cs b/test/Apache.Arrow.Tests/ArrowGoInteropFixture.cs new file mode 100644 index 00000000..17a86c07 --- /dev/null +++ b/test/Apache.Arrow.Tests/ArrowGoInteropFixture.cs @@ -0,0 +1,237 @@ +// 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. + +#if NET5_0_OR_GREATER + +using System; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; +using System.Threading.Tasks; +using Apache.Arrow.C; +using Apache.Arrow.Ipc; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Loads the arrow-go interop shim (test/arrow-go-interop), a c-shared + /// library wrapping arrow-go's C Async Device Stream implementation. + /// + /// + /// The library path comes from the ARROW_GO_INTEROP_LIB environment variable; + /// ci/scripts/build_go_interop.sh builds it. The Go runtime can't be unloaded, + /// so the library stays loaded for the life of the process. + /// + [Experimental("ArrowAsyncDeviceStreamApi")] + public sealed unsafe class ArrowGoInteropFixture + { + public const string LibraryEnvironmentVariable = "ARROW_GO_INTEROP_LIB"; + + private readonly string _unavailableReason; + + private readonly delegate* unmanaged[Cdecl] _freeError; + private readonly delegate* unmanaged[Cdecl] _produceFromStream; + private readonly delegate* unmanaged[Cdecl] _consumerCreate; + private readonly delegate* unmanaged[Cdecl] _consumerToStream; + private readonly delegate* unmanaged[Cdecl] _consumerCancel; + private readonly delegate* unmanaged[Cdecl] _consumerFree; + + public ArrowGoInteropFixture() + { + string path = Environment.GetEnvironmentVariable(LibraryEnvironmentVariable); + if (string.IsNullOrEmpty(path)) + { + _unavailableReason = $"{LibraryEnvironmentVariable} not set"; + return; + } + + IntPtr library; + try + { + library = NativeLibrary.Load(path); + } + catch (Exception ex) + { + _unavailableReason = $"could not load {path}: {ex.Message}"; + return; + } + + _freeError = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_FreeError"); + _produceFromStream = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_ProduceFromStream"); + _consumerCreate = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_ConsumerCreate"); + _consumerToStream = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_ConsumerToStream"); + _consumerCancel = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_ConsumerCancel"); + _consumerFree = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_ConsumerFree"); + + // The test host swallows stderr, so a Go fatal error otherwise just + // looks like "test host process crashed". + string crashLog = Environment.GetEnvironmentVariable(CrashLogEnvironmentVariable); + if (!string.IsNullOrEmpty(crashLog)) + { + var setCrashOutput = (delegate* unmanaged[Cdecl])NativeLibrary.GetExport(library, "ArrowGoAsync_SetCrashOutput"); + IntPtr crashLogPtr = Marshal.StringToCoTaskMemUTF8(crashLog); + try + { + ThrowIfError(setCrashOutput((byte*)crashLogPtr)); + } + finally + { + Marshal.FreeCoTaskMem(crashLogPtr); + } + } + } + + public const string CrashLogEnvironmentVariable = "ARROW_GO_INTEROP_CRASH_LOG"; + + /// + /// Set to "1" (as the go-interop CI job does) to make a missing shim fail the + /// tests instead of skipping them. + /// + public const string RequiredEnvironmentVariable = "ARROW_GO_INTEROP_REQUIRED"; + + /// + /// Skips the calling test if the shim isn't available, unless + /// says it must be. Unlike the + /// Python tests, these don't run in every CI job: building the shim needs Go + /// and cgo, so it has its own job. + /// + public void EnsureAvailable() + { + if (_unavailableReason == null) + { + return; + } + + bool required = Environment.GetEnvironmentVariable(RequiredEnvironmentVariable) == "1"; + Skip.IfNot(required, $"{_unavailableReason}; skipping arrow-go interop tests."); + + throw new Exception($"{_unavailableReason}; cannot run arrow-go interop tests."); + } + + /// + /// Has arrow-go produce every batch of through + /// . Completes after arrow-go has released the handler. + /// + /// If non-negative, arrow-go reports an error after this many batches. + public Task ProduceFromStreamAsync(IArrowArrayStream source, CArrowAsyncDeviceStreamHandler* handler, long failAfter = -1) + { + // Export on the calling thread so failures surface synchronously. + CArrowArrayStream* cStream = CArrowArrayStream.Create(); + CArrowArrayStreamExporter.ExportArrayStream(source, cStream); + + IntPtr streamPtr = (IntPtr)cStream; + IntPtr handlerPtr = (IntPtr)handler; + return Task.Factory.StartNew(() => + { + CArrowArrayStream* stream = (CArrowArrayStream*)streamPtr; + try + { + // arrow-go's async producer blocks until the stream is done. + ThrowIfError(_produceFromStream(stream, (CArrowAsyncDeviceStreamHandler*)handlerPtr, failAfter)); + } + finally + { + // arrow-go moved the stream out; Free releases it only if it didn't. + CArrowArrayStream.Free(stream); + } + }, TaskCreationOptions.LongRunning); + } + + /// + /// Populates with arrow-go's async consumer. + /// + /// Batches arrow-go requests up front; it then requests one per batch consumed. + public GoConsumer CreateConsumer(CArrowAsyncDeviceStreamHandler* handler, ulong queueSize) + { + nuint id; + ThrowIfError(_consumerCreate(handler, queueSize, &id)); + return new GoConsumer(this, id); + } + + private void ThrowIfError(byte* error) + { + if (error == null) + { + return; + } + + string message = Marshal.PtrToStringUTF8((IntPtr)error); + _freeError(error); + throw new ArrowGoInteropException(message); + } + + /// + /// An arrow-go async consumer attached to a handler. + /// + public sealed class GoConsumer : IDisposable + { + private readonly ArrowGoInteropFixture _fixture; + private readonly nuint _id; + private bool _disposed; + + internal GoConsumer(ArrowGoInteropFixture fixture, nuint id) + { + _fixture = fixture; + _id = id; + } + + /// + /// Waits for the producer to deliver the schema, then returns what + /// arrow-go consumes as a synchronous stream. Errors the producer + /// reports later surface from ReadNextRecordBatchAsync. + /// + /// + /// arrow-go's on_schema blocks until this has been called, so start it + /// before (or concurrently with) the producer. + /// + public Task ToStreamAsync() + { + return Task.Factory.StartNew(() => + { + CArrowArrayStream* cStream = CArrowArrayStream.Create(); + try + { + _fixture.ThrowIfError(_fixture._consumerToStream(_id, cStream)); + return CArrowArrayStreamImporter.ImportArrayStream(cStream); + } + finally + { + CArrowArrayStream.Free(cStream); + } + }, TaskCreationOptions.LongRunning); + } + + public void Cancel() => _fixture._consumerCancel(_id); + + public void Dispose() + { + if (!_disposed) + { + _disposed = true; + _fixture._consumerFree(_id); + } + } + } + } + + public sealed class ArrowGoInteropException : Exception + { + public ArrowGoInteropException(string message) : base(message) + { + } + } +} + +#endif diff --git a/test/Apache.Arrow.Tests/CAsyncDeviceStreamGoInteropTests.cs b/test/Apache.Arrow.Tests/CAsyncDeviceStreamGoInteropTests.cs new file mode 100644 index 00000000..ee341623 --- /dev/null +++ b/test/Apache.Arrow.Tests/CAsyncDeviceStreamGoInteropTests.cs @@ -0,0 +1,510 @@ +// 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. + +#if NET5_0_OR_GREATER + +using System; +using System.Collections.Generic; +using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; +using System.Threading; +using System.Threading.Tasks; +using Apache.Arrow.C; +using Apache.Arrow.Ipc; +using Apache.Arrow.Types; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Interop tests for the C Async Device Stream Interface against arrow-go. + /// See test/arrow-go-interop for the Go side. + /// + [Experimental("ArrowAsyncDeviceStreamApi")] + public class CAsyncDeviceStreamGoInteropTests : IClassFixture + { + // Must match injectedErrorMessage in test/arrow-go-interop/main.go. + private const string GoInjectedErrorMessage = "arrow-go-interop: injected producer failure"; + + private static readonly TimeSpan Timeout = TimeSpan.FromSeconds(30); + + private readonly ArrowGoInteropFixture _go; + + public CAsyncDeviceStreamGoInteropTests(ArrowGoInteropFixture go) + { + _go = go; + _go.EnsureAvailable(); + } + + // ---- arrow-go producer -> .NET consumer ---- + + [SkippableFact] + public async Task GoProducerToDotNetConsumer() + { + List batches = CreateBatches(3); + + await WithDotNetConsumer(async (received, produceWith) => + { + Task produce = produceWith(new BatchListStream(batches), -1); + + await AssertStreamEquals(batches, received); + await produce.WaitAsync(Timeout); + }); + } + + [SkippableFact] + public async Task GoProducerToDotNetConsumerEmptyStream() + { + Schema schema = CreateBatches(1)[0].Schema; + + await WithDotNetConsumer(async (received, produceWith) => + { + Task produce = produceWith(new BatchListStream(schema, new List()), -1); + + Assert.Null(await received.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout)); + SchemaComparer.Compare(schema, received.Schema); + await produce.WaitAsync(Timeout); + }); + } + + [SkippableFact] + public async Task GoProducerErrorReachesDotNetConsumer() + { + List batches = CreateBatches(3); + + await WithDotNetConsumer(async (received, produceWith) => + { + Task produce = produceWith(new BatchListStream(batches), 1); + + RecordBatch first = await received.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout); + Assert.NotNull(first); + ArrowReaderVerifier.CompareBatches(batches[0], first, strictCompare: false); + first.Dispose(); + + Exception readError = await Assert.ThrowsAnyAsync( + () => received.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout)); + Assert.Contains(GoInjectedErrorMessage, readError.Message); + + // arrow-go's producer reports the same error to its caller. + ArrowGoInteropException produceError = await Assert.ThrowsAsync( + () => produce.WaitAsync(Timeout)); + Assert.Contains(GoInjectedErrorMessage, produceError.Message); + }); + } + + [SkippableFact] + public async Task DotNetConsumerDisposeCancelsGoProducer() + { + RecordBatch batch = CreateBatches(1)[0]; + + await WithDotNetConsumer(async (received, produceWith) => + { + Task produce = produceWith(new EndlessStream(batch), -1); + + for (int i = 0; i < 5; i++) + { + RecordBatch result = await received.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout); + Assert.NotNull(result); + result.Dispose(); + } + + // Disposing calls the producer's cancel; arrow-go must then stop, + // release the handler, and return without an error. + received.Dispose(); + await produce.WaitAsync(Timeout); + }); + } + + // ---- .NET producer -> arrow-go consumer ---- + + // arrow-go requests queueSize batches up front, then one per batch consumed, + // so small queue sizes exercise the producer's handling of repeated request() calls. + [SkippableTheory] + [InlineData(1)] + [InlineData(2)] + [InlineData(16)] + public async Task DotNetProducerToGoConsumer(int queueSize) + { + List batches = CreateBatches(8); + + await WithGoConsumer((ulong)queueSize, new BatchListStream(batches), async result => + { + await AssertStreamEquals(batches, result); + }); + } + + [SkippableFact] + public async Task GoConsumerCancelStopsDotNetProducer() + { + RecordBatch batch = CreateBatches(1)[0]; + + await WithGoConsumer(2, new EndlessStream(batch), async (result, consumer) => + { + for (int i = 0; i < 5; i++) + { + RecordBatch received = await result.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout); + Assert.NotNull(received); + received.Dispose(); + } + + // arrow-go calls the producer's cancel; the .NET producer must then + // release the handler, which ends arrow-go's stream. Any batches + // already in flight may still arrive first. + consumer.Cancel(); + while (await result.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout) is RecordBatch extra) + { + extra.Dispose(); + } + }); + } + + [SkippableFact] + public async Task GoConsumerRejectingSchemaReleasesCleanly() + { + // Act as a producer by hand, sending a schema arrow-go can't import. After + // a failed on_schema the spec says the producer calls only release, which + // must not crash (arrow-go v18.8.0 frees its handler state in on_schema + // but leaves its release callback installed; apache/arrow-go#1573). + IntPtr handlerPtr; + IntPtr producerPtr = IntPtr.Zero; + ArrowGoInteropFixture.GoConsumer consumer; + unsafe + { + CArrowAsyncDeviceStreamHandler* handler = CArrowAsyncDeviceStreamHandler.Create(); + handlerPtr = (IntPtr)handler; + consumer = _go.CreateConsumer(handler, 1); + } + + try + { + Task resultTask = consumer.ToStreamAsync(); + + unsafe + { + var handler = (CArrowAsyncDeviceStreamHandler*)handlerPtr; + CArrowAsyncProducer* producer = CArrowAsyncProducer.Create(); + producerPtr = (IntPtr)producer; + producer->device_type = ArrowDeviceType.Cpu; + producer->request = &NoOpRequest; + producer->cancel = &NoOpCancel; + handler->producer = producer; + + CArrowSchema* schema = CArrowSchema.Create(); + CArrowSchemaExporter.ExportType(Int32Type.Default, schema); + byte* exportedFormat = schema->format; + schema->format = StringUtil.ToCStringUtf8("~bogus"); + Marshal.FreeHGlobal((IntPtr)exportedFormat); + + int errno = handler->on_schema(handler, schema); + Assert.NotEqual(0, errno); + + // As the spec requires after a failed on_schema: only release. + handler->release(handler); + CArrowSchema.Free(schema); + } + + // arrow-go reports the import failure instead of a stream. + await Assert.ThrowsAsync(() => resultTask.WaitAsync(Timeout)); + } + finally + { + bool released = await WaitForHandlerReleaseAsync(handlerPtr); + consumer.Dispose(); + if (released) + { + unsafe + { + CArrowAsyncDeviceStreamHandler.Free((CArrowAsyncDeviceStreamHandler*)handlerPtr); + CArrowAsyncProducer.Free((CArrowAsyncProducer*)producerPtr); + } + } + } + } + + [UnmanagedCallersOnly] + private static unsafe void NoOpRequest(CArrowAsyncProducer* producer, long n) + { + } + + [UnmanagedCallersOnly] + private static unsafe void NoOpCancel(CArrowAsyncProducer* producer) + { + } + + [SkippableFact] + public async Task DotNetProducerToGoConsumerEmptyStream() + { + Schema schema = CreateBatches(1)[0].Schema; + + await WithGoConsumer(4, new BatchListStream(schema, new List()), async result => + { + SchemaComparer.Compare(schema, result.Schema); + Assert.Null(await result.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout)); + }); + } + + [SkippableFact] + public async Task DotNetProducerErrorReachesGoConsumer() + { + List batches = CreateBatches(3); + const string message = "dotnet source failure"; + + await WithGoConsumer(1, new BatchListStream(batches, failAfter: 1, failureMessage: message), async result => + { + RecordBatch first = await result.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout); + Assert.NotNull(first); + ArrowReaderVerifier.CompareBatches(batches[0], first, strictCompare: false); + first.Dispose(); + + Exception readError = await Assert.ThrowsAnyAsync( + () => result.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout)); + Assert.Contains(message, readError.Message); + }); + } + + // ---- helpers ---- + + private delegate Task ProduceWith(IArrowArrayStream source, long failAfter); + + /// + /// Runs with a .NET consumer whose handler arrow-go + /// produces into. The consumer frees the handler itself when arrow-go + /// releases it. + /// + private async Task WithDotNetConsumer(Func body) + { + IntPtr handlerPtr; + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + handlerPtr = (IntPtr)handler; + } + + Task produce = null; + try + { + await body(received, (source, failAfter) => + { + unsafe + { + produce = _go.ProduceFromStreamAsync(source, (CArrowAsyncDeviceStreamHandler*)handlerPtr, failAfter); + } + return produce; + }); + } + finally + { + received.Dispose(); + + // Don't leave arrow-go's producer running into the next test. Tests + // that care about its outcome have already asserted on it. + if (produce != null) + { + try + { + await produce.WaitAsync(Timeout); + } + catch (Exception) + { + } + } + } + } + + /// + /// Runs with what arrow-go consumes when the .NET + /// producer produces into it. + /// + private Task WithGoConsumer(ulong queueSize, IArrowArrayStream source, Func body) + { + return WithGoConsumer(queueSize, source, (result, _) => body(result)); + } + + private async Task WithGoConsumer(ulong queueSize, IArrowArrayStream source, Func body) + { + IntPtr handlerPtr; + ArrowGoInteropFixture.GoConsumer consumer; + unsafe + { + CArrowAsyncDeviceStreamHandler* handler = CArrowAsyncDeviceStreamHandler.Create(); + handlerPtr = (IntPtr)handler; + consumer = _go.CreateConsumer(handler, queueSize); + } + + bool released = false; + try + { + // arrow-go's on_schema blocks until someone is waiting for the stream. + Task resultTask = consumer.ToStreamAsync(); + unsafe + { + CArrowAsyncDeviceStreamProducer.Produce(source, (CArrowAsyncDeviceStreamHandler*)handlerPtr); + } + + using (IArrowArrayStream result = await resultTask.WaitAsync(Timeout)) + { + await body(result, consumer); + } + } + finally + { + // If release never happens, leak the handler rather than free memory + // the producer may still use. + released = await WaitForHandlerReleaseAsync(handlerPtr); + consumer.Dispose(); + if (released) + { + unsafe + { + CArrowAsyncDeviceStreamHandler.Free((CArrowAsyncDeviceStreamHandler*)handlerPtr); + } + } + } + + // Only reached if the body succeeded, so this doesn't mask its failure. + Assert.True(released, "The .NET producer never released the handler."); + } + + /// + /// The .NET producer releases the handler after it signals end-of-stream, + /// so the consumer can finish reading before release happens. The shim + /// clears the release callback as its very last access to the handler. + /// + private static async Task WaitForHandlerReleaseAsync(IntPtr handlerPtr) + { + var stopwatch = Stopwatch.StartNew(); + while (stopwatch.Elapsed < Timeout) + { + if (IsReleased(handlerPtr)) + { + return true; + } + await Task.Delay(10); + } + return false; + } + + private static unsafe bool IsReleased(IntPtr handlerPtr) + { + // Pairs with the shim's release-ordered store, so nothing it wrote to the + // handler can land after we see the callback cleared and free it. + var handler = (CArrowAsyncDeviceStreamHandler*)handlerPtr; + return Volatile.Read(ref *(IntPtr*)&handler->release) == IntPtr.Zero; + } + + private static async Task AssertStreamEquals(List expected, IArrowArrayStream actual) + { + for (int i = 0; i < expected.Count; i++) + { + RecordBatch batch = await actual.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout); + Assert.True(batch != null, $"Stream ended after {i} of {expected.Count} batches."); + using (batch) + { + ArrowReaderVerifier.CompareBatches(expected[i], batch, strictCompare: false); + } + } + + Assert.Null(await actual.ReadNextRecordBatchAsync().AsTask().WaitAsync(Timeout)); + } + + /// + /// Batches sharing one schema with many column types. Each batch has a + /// different length so out-of-order delivery is detected. + /// + private static List CreateBatches(int count) + { + RecordBatch first = TestData.CreateSampleRecordBatch(length: 10); + var batches = new List { first }; + for (int i = 1; i < count; i++) + { + batches.Add(TestData.CreateSampleRecordBatch(first.Schema, length: 10 + i)); + } + return batches; + } + + /// + /// Stream that never ends, so only cancellation can stop the producer. + /// + private sealed class EndlessStream : IArrowArrayStream + { + private readonly RecordBatch _batch; + + public EndlessStream(RecordBatch batch) + { + _batch = batch; + } + + public Schema Schema => _batch.Schema; + + public ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + // The exporters take ownership of (and dispose) each batch they're given. + return new ValueTask(_batch.Clone()); + } + + public void Dispose() + { + } + } + + /// + /// Stream over a list of batches that can fail partway through. It hands + /// out clones, so tests can compare against the originals. + /// + private sealed class BatchListStream : IArrowArrayStream + { + private readonly IReadOnlyList _batches; + private readonly int _failAfter; + private readonly string _failureMessage; + private int _next; + + public BatchListStream(IReadOnlyList batches, int failAfter = -1, string failureMessage = null) + : this(batches[0].Schema, batches, failAfter, failureMessage) + { + } + + public BatchListStream(Schema schema, IReadOnlyList batches, int failAfter = -1, string failureMessage = null) + { + Schema = schema; + _batches = batches; + _failAfter = failAfter; + _failureMessage = failureMessage; + } + + public Schema Schema { get; } + + public ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + if (_failAfter >= 0 && _next == _failAfter) + { + throw new InvalidOperationException(_failureMessage); + } + + // The exporters take ownership of (and dispose) each batch they're + // given, so hand out clones and keep the originals for comparison. + RecordBatch batch = _next < _batches.Count ? _batches[_next++].Clone() : null; + return new ValueTask(batch); + } + + public void Dispose() + { + } + } + } +} + +#endif diff --git a/test/Apache.Arrow.Tests/CAsyncDeviceStreamTests.cs b/test/Apache.Arrow.Tests/CAsyncDeviceStreamTests.cs new file mode 100644 index 00000000..bd7f263a --- /dev/null +++ b/test/Apache.Arrow.Tests/CAsyncDeviceStreamTests.cs @@ -0,0 +1,1113 @@ +// 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; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Runtime.InteropServices; +using System.Threading; +using System.Threading.Tasks; +using Apache.Arrow.C; +using Apache.Arrow.Ipc; +using Apache.Arrow.Types; +using Xunit; + +namespace Apache.Arrow.Tests +{ + [Experimental("ArrowAsyncDeviceStreamApi")] + public class CAsyncDeviceStreamTests + { + private RecordBatch CreateBatch(int startValue, int count) + { + var builder = new Int32Array.Builder(); + for (int i = 0; i < count; i++) + { + builder.Append(startValue + i); + } + + return new RecordBatch.Builder() + .Append("values", false, col => col.Int32(b => + { + for (int i = 0; i < count; i++) + { + b.Append(startValue + i); + } + })) + .Build(); + } + + [Fact] + public async Task RoundTripSingleBatch() + { + RecordBatch batch = CreateBatch(1, 5); + IArrowArrayStream source = new TestArrayStream(batch.Schema, batch); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + RecordBatch result = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(result); + Assert.Equal(5, result.Length); + + Int32Array values = (Int32Array)result.Column(0); + Assert.Equal(1, values.GetValue(0)); + Assert.Equal(5, values.GetValue(4)); + + result.Dispose(); + + RecordBatch end = await received.ReadNextRecordBatchAsync(); + Assert.Null(end); + } + } + + [Fact] + public async Task RoundTripMultipleBatches() + { + RecordBatch batch1 = CreateBatch(0, 3); + RecordBatch batch2 = CreateBatch(10, 3); + RecordBatch batch3 = CreateBatch(20, 3); + IArrowArrayStream source = new TestArrayStream(batch1.Schema, batch1, batch2, batch3); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + RecordBatch r1 = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(r1); + Assert.Equal(0, ((Int32Array)r1.Column(0)).GetValue(0)); + r1.Dispose(); + + RecordBatch r2 = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(r2); + Assert.Equal(10, ((Int32Array)r2.Column(0)).GetValue(0)); + r2.Dispose(); + + RecordBatch r3 = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(r3); + Assert.Equal(20, ((Int32Array)r3.Column(0)).GetValue(0)); + r3.Dispose(); + + RecordBatch end = await received.ReadNextRecordBatchAsync(); + Assert.Null(end); + } + } + + [Fact] + public async Task EmptyStream() + { + Schema schema = new Schema.Builder() + .Field(f => f.Name("x").DataType(Int32Type.Default)) + .Build(); + IArrowArrayStream source = new TestArrayStream(schema); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + Assert.Equal("x", received.Schema.FieldsList[0].Name); + + RecordBatch end = await received.ReadNextRecordBatchAsync(); + Assert.Null(end); + } + } + + [Fact] + public async Task SchemaIsPreserved() + { + Schema schema = new Schema.Builder() + .Field(f => f.Name("col_a").DataType(Int64Type.Default).Nullable(true)) + .Field(f => f.Name("col_b").DataType(StringType.Default).Nullable(false)) + .Build(); + IArrowArrayStream source = new TestArrayStream(schema); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + // Wait for end of stream so schema is definitely available + RecordBatch end = await received.ReadNextRecordBatchAsync(); + Assert.Null(end); + + Assert.Equal(2, received.Schema.FieldsList.Count); + Assert.Equal("col_a", received.Schema.FieldsList[0].Name); + Assert.Equal(ArrowTypeId.Int64, received.Schema.FieldsList[0].DataType.TypeId); + Assert.Equal("col_b", received.Schema.FieldsList[1].Name); + Assert.Equal(ArrowTypeId.String, received.Schema.FieldsList[1].DataType.TypeId); + } + } + + [Fact] + public unsafe void InitializeStructsZeroed() + { + CArrowAsyncTask task = default; + Assert.True(task.extract_data == default); + Assert.True(task.private_data == null); + + CArrowAsyncProducer* producer = CArrowAsyncProducer.Create(); + Assert.Equal((ArrowDeviceType)0, producer->device_type); + Assert.True(producer->request == default); + Assert.True(producer->cancel == default); + Assert.True(producer->additional_metadata == null); + Assert.True(producer->private_data == null); + CArrowAsyncProducer.Free(producer); + + CArrowAsyncDeviceStreamHandler* handler = CArrowAsyncDeviceStreamHandler.Create(); + Assert.True(handler->on_schema == default); + Assert.True(handler->on_next_task == default); + Assert.True(handler->on_error == default); + Assert.True(handler->release == default); + Assert.True(handler->producer == null); + Assert.True(handler->private_data == null); + CArrowAsyncDeviceStreamHandler.Free(handler); + } + + [Fact] + public async Task ProducerSetsDeviceTypeCpu() + { + RecordBatch batch = CreateBatch(1, 1); + IArrowArrayStream source = new TestArrayStream(batch.Schema, batch); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + RecordBatch r = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(r); + // If we got data, the producer was using CPU device type + // (verified by the fact that CArrowDeviceArrayImporter accepted it) + r.Dispose(); + + RecordBatch end = await received.ReadNextRecordBatchAsync(); + Assert.Null(end); + } + } + + [Fact] + public async Task CancelledReadDoesNotLoseBatch() + { + RecordBatch batch = CreateBatch(42, 2); + var gate = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + var source = new GatedArrayStream(batch.Schema, gate.Task, batch); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + // Start a read while the producer is blocked, then cancel it. + using (var cts = new CancellationTokenSource()) + { + Task pending = received.ReadNextRecordBatchAsync(cts.Token).AsTask(); + cts.Cancel(); + await Assert.ThrowsAnyAsync(() => pending); + } + + // Let the producer deliver; the batch must go to the next read, + // not to the cancelled one. + gate.SetResult(true); + + RecordBatch result = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(result); + Assert.Equal(42, ((Int32Array)result.Column(0)).GetValue(0)); + result.Dispose(); + + RecordBatch end = await received.ReadNextRecordBatchAsync(); + Assert.Null(end); + } + } + + [Fact] + public async Task SchemaExportFailureSignalsErrorAndReleases() + { + var source = new ThrowingSchemaArrayStream("schema export failed"); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + Exception readError = await Assert.ThrowsAnyAsync( + () => received.ReadNextRecordBatchAsync().AsTask()); + Assert.Contains("schema export failed", readError.Message); + + Exception schemaError = Assert.ThrowsAny(() => received.Schema); + Assert.Contains("schema export failed", schemaError.Message); + + // The producer finished, so it must have disposed its source. + Assert.True(source.IsDisposed); + } + } + + [Theory] + [InlineData(1)] + [InlineData(3)] + [InlineData(64)] + public async Task ManyBatchesArriveInOrder(long queueSize) + { + // Small queue sizes make the consumer call request() repeatedly while the + // producer is running, which used to start overlapping produce loops. + const int count = 200; + var batches = new RecordBatch[count]; + for (int i = 0; i < count; i++) + { + batches[i] = CreateBatch(i * 10, 1 + i % 7); + } + var source = new YieldingArrayStream(batches[0].Schema, batches); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler, queueSize); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + using (received) + { + for (int i = 0; i < count; i++) + { + RecordBatch result = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(result); + Assert.Equal(batches[i].Length, result.Length); + Assert.Equal(i * 10, ((Int32Array)result.Column(0)).GetValue(0)); + result.Dispose(); + } + + Assert.Null(await received.ReadNextRecordBatchAsync()); + } + + // The producer must never read its source from two loops at once. + Assert.Equal(1, source.MaxConcurrentReads); + } + + [Fact] + public async Task DisposingConsumerCancelsAndReleases() + { + RecordBatch batch = CreateBatch(0, 4); + var source = new EndlessArrayStream(batch); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler, queueSize: 2); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + for (int i = 0; i < 5; i++) + { + RecordBatch result = await received.ReadNextRecordBatchAsync(); + Assert.NotNull(result); + result.Dispose(); + } + + received.Dispose(); + + // Cancelling must lead to release (and no on_error). The producer + // disposes its source right after calling release. + Assert.True(await WaitUntilAsync(() => source.IsDisposed), "Producer did not release after cancel."); + } + + [Fact] + public async Task DisposingConsumerBeforeReadingReleases() + { + var source = new EndlessArrayStream(CreateBatch(0, 1)); + + unsafe + { + IArrowArrayStream received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + received.Dispose(); + } + + Assert.True(await WaitUntilAsync(() => source.IsDisposed), "Producer did not release after cancel."); + } + + [Theory] + [InlineData(0L)] + [InlineData(-1L)] + [InlineData(long.MinValue)] + public async Task InvalidRequestReportsErrorAndReleases(long n) + { + var source = new TestArrayStream(CreateBatch(0, 3).Schema, CreateBatch(0, 3), CreateBatch(3, 3)); + var consumer = new RecordingConsumer(requestInOnSchema: n); + + unsafe + { + CArrowAsyncDeviceStreamProducer.Produce(source, consumer.Handler); + } + + Task released = consumer.Released; + Assert.True(await Task.WhenAny(released, Task.Delay(TimeSpan.FromSeconds(10))) == released, "Handler was not released."); + + // The spec says n <= 0 is invalid and the producer should call on_error; + // after on_error comes release, and nothing is delivered. + IReadOnlyList events = consumer.Events; + Assert.Equal(3, events.Count); + Assert.Equal("schema", events[0]); + Assert.StartsWith("error:22:", events[1]); // EINVAL + Assert.Contains("must be positive", events[1]); + Assert.Equal("release", events[2]); + Assert.False(consumer.SawOverlappingCallbacks); + + // The producer disposes its source after the release callback returns, + // which can be after Released completes. + Assert.True(await WaitUntilAsync(() => source.IsDisposed), "Source was not disposed after release."); + } + + [Fact] + public async Task DisposingConsumerBeforeProducerAttachesReleases() + { + // The consumer can't cancel a producer that isn't attached yet, so it has + // to send the cancel once on_schema arrives; otherwise the producer gets + // neither demand nor cancel and never releases. + var source = new EndlessArrayStream(CreateBatch(0, 1)); + + unsafe + { + IArrowArrayStream received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + received.Dispose(); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + Assert.True(await WaitUntilAsync(() => source.IsDisposed), "Producer did not release after cancel."); + } + + [Fact] + public async Task CancelInterruptsPendingSourceRead() + { + // A source waiting for input must be woken by cancel; otherwise the + // producer never gets to release. + var source = new WaitingArrayStream(CreateBatch(0, 1).Schema); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + CArrowAsyncDeviceStreamProducer.Produce(source, handler); + } + + Assert.True(await WaitUntilAsync(() => source.ReadStarted), "Producer never started reading."); + received.Dispose(); + + Assert.True(await WaitUntilAsync(() => source.IsDisposed), "Producer did not release after cancel."); + Assert.True(source.ReadWasCancelled); + } + + [Fact] + public async Task SchemaImportFailureIsReported() + { + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + + // Act as a producer that sends a schema the importer rejects. + CArrowSchema* schema = CArrowSchema.Create(); + CArrowSchemaExporter.ExportType(Int32Type.Default, schema); + byte* exportedFormat = schema->format; + schema->format = StringUtil.ToCStringUtf8("~bogus"); + Marshal.FreeHGlobal((IntPtr)exportedFormat); + +#if NET5_0_OR_GREATER + int errno = handler->on_schema(handler, schema); +#else + int errno = NativeDelegate.GetDelegateForFunctionPointer(handler->on_schema)(handler, schema); +#endif + Assert.NotEqual(0, errno); + + // Per the spec, a failed on_schema is followed only by release. +#if NET5_0_OR_GREATER + handler->release(handler); +#else + NativeDelegate.GetDelegateForFunctionPointer(handler->release)(handler); +#endif + CArrowSchema.Free(schema); + } + + using (received) + { + // The reader must see the import failure, not an empty stream. + Exception readError = await Assert.ThrowsAnyAsync( + () => received.ReadNextRecordBatchAsync().AsTask()); + Assert.Contains("not yet supported", readError.Message); + + Exception schemaError = Assert.ThrowsAny(() => received.Schema); + Assert.Contains("not yet supported", schemaError.Message); + } + } + + [Fact] + public async Task ProducerReleasingSynchronouslyFromCancelDoesNotDeadlock() + { + // The consumer holds a lock while calling cancel so release can't free the + // producer mid-call; release takes the same lock. A producer may call + // release from inside cancel, on the same thread, and that must not deadlock. + Schema schema = CreateBatch(0, 1).Schema; + var producer = new ReleaseOnCancelProducer(); + + IArrowArrayStream received; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + producer.Attach(handler, schema); + } + + // On another task so a deadlock fails the test instead of hanging it. + Task dispose = Task.Run(() => received.Dispose()); + Assert.True(await Task.WhenAny(dispose, Task.Delay(TimeSpan.FromSeconds(10))) == dispose, "Dispose deadlocked."); + await dispose; + + Assert.True(producer.ReleasedInsideCancel, "The producer's cancel did not release the handler."); + } + + [Fact] + public async Task FailedExtractIsReportedWithoutOnError() + { + // A producer can't always follow a failed extract_data with on_error (for + // example if the consumer extracts after it has finished), so the consumer + // must not silently drop the batch and end the stream normally. + Schema schema = CreateBatch(0, 1).Schema; + var producer = new FailingExtractProducer(); + + IArrowArrayStream received; + int status; + unsafe + { + received = CArrowAsyncDeviceStreamConsumer.CreateStream(out CArrowAsyncDeviceStreamHandler* handler); + status = producer.DeliverFailingTaskAndRelease(handler, schema); + } + + // The consumer tells the producer to stop... + Assert.NotEqual(0, status); + + using (received) + { + // ...and the reader sees the failure instead of an empty stream. + Exception readError = await Assert.ThrowsAnyAsync( + () => received.ReadNextRecordBatchAsync().AsTask()); + Assert.Contains($"Error code: {FailingExtractProducer.ExtractError}", readError.Message); + } + } + + /// + /// A minimal producer that delivers one task whose extract_data fails, then + /// releases the handler without calling on_error. + /// + private sealed unsafe class FailingExtractProducer + { + public const int ExtractError = 5; // EIO + + public int DeliverFailingTaskAndRelease(CArrowAsyncDeviceStreamHandler* handler, Schema schema) + { + CArrowAsyncProducer* producer = CArrowAsyncProducer.Create(); + producer->device_type = ArrowDeviceType.Cpu; +#if NET5_0_OR_GREATER + producer->request = &Request; + producer->cancel = &Cancel; +#else + producer->request = Marshal.GetFunctionPointerForDelegate(s_request); + producer->cancel = Marshal.GetFunctionPointerForDelegate(s_cancel); +#endif + handler->producer = producer; + + CArrowSchema cSchema = default; + CArrowSchemaExporter.ExportSchema(schema, &cSchema); + CArrowAsyncTask task = default; +#if NET5_0_OR_GREATER + Assert.Equal(0, handler->on_schema(handler, &cSchema)); + task.extract_data = &FailingExtract; + int status = handler->on_next_task(handler, &task, null); + handler->release(handler); +#else + Assert.Equal(0, NativeDelegate.GetDelegateForFunctionPointer(handler->on_schema)(handler, &cSchema)); + task.extract_data = Marshal.GetFunctionPointerForDelegate(s_extract); + int status = NativeDelegate.GetDelegateForFunctionPointer(handler->on_next_task)(handler, &task, null); + NativeDelegate.GetDelegateForFunctionPointer(handler->release)(handler); +#endif + // After release, the producer may free itself. + CArrowAsyncProducer.Free(producer); + return status; + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static void Request(CArrowAsyncProducer* producer, long n) + { + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static void Cancel(CArrowAsyncProducer* producer) + { + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static int FailingExtract(CArrowAsyncTask* task, CArrowDeviceArray* array) + { + return ExtractError; + } + +#if !NET5_0_OR_GREATER + private delegate void RequestDelegate(CArrowAsyncProducer* producer, long n); + private delegate void CancelDelegate(CArrowAsyncProducer* producer); + private delegate int ExtractDelegate(CArrowAsyncTask* task, CArrowDeviceArray* array); + + // Kept in static fields so the delegates outlive the function pointers. + private static readonly RequestDelegate s_request = Request; + private static readonly CancelDelegate s_cancel = Cancel; + private static readonly ExtractDelegate s_extract = FailingExtract; +#endif + } + + /// + /// A minimal producer whose cancel calls the handler's release synchronously, + /// then frees itself, as the spec allows. + /// + private sealed unsafe class ReleaseOnCancelProducer + { + private CArrowAsyncDeviceStreamHandler* _handler; + private CArrowAsyncProducer* _producer; + private GCHandle _self; + private int _releasedInsideCancel; + + public bool ReleasedInsideCancel => Volatile.Read(ref _releasedInsideCancel) != 0; + + public void Attach(CArrowAsyncDeviceStreamHandler* handler, Schema schema) + { + _handler = handler; + _self = GCHandle.Alloc(this); + + _producer = CArrowAsyncProducer.Create(); + _producer->device_type = ArrowDeviceType.Cpu; +#if NET5_0_OR_GREATER + _producer->request = &Request; + _producer->cancel = &Cancel; +#else + _producer->request = Marshal.GetFunctionPointerForDelegate(s_request); + _producer->cancel = Marshal.GetFunctionPointerForDelegate(s_cancel); +#endif + _producer->private_data = (void*)GCHandle.ToIntPtr(_self); + handler->producer = _producer; + + CArrowSchema cSchema = default; + CArrowSchemaExporter.ExportSchema(schema, &cSchema); +#if NET5_0_OR_GREATER + int errno = handler->on_schema(handler, &cSchema); +#else + int errno = NativeDelegate.GetDelegateForFunctionPointer(handler->on_schema)(handler, &cSchema); +#endif + Assert.Equal(0, errno); + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static void Request(CArrowAsyncProducer* producer, long n) + { + // This producer never delivers anything. + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static void Cancel(CArrowAsyncProducer* producer) + { + var self = (ReleaseOnCancelProducer)GCHandle.FromIntPtr((IntPtr)producer->private_data).Target; + CArrowAsyncDeviceStreamHandler* handler = self._handler; + +#if NET5_0_OR_GREATER + handler->release(handler); +#else + NativeDelegate.GetDelegateForFunctionPointer(handler->release)(handler); +#endif + Interlocked.Exchange(ref self._releasedInsideCancel, 1); + + // After release, the producer may free itself. + self._self.Free(); + CArrowAsyncProducer.Free(producer); + } + +#if !NET5_0_OR_GREATER + private delegate void RequestDelegate(CArrowAsyncProducer* producer, long n); + private delegate void CancelDelegate(CArrowAsyncProducer* producer); + + // Kept in static fields so the delegates outlive the function pointers. + private static readonly RequestDelegate s_request = Request; + private static readonly CancelDelegate s_cancel = Cancel; +#endif + } + + /// + /// Stream whose reads wait for input that never comes, but honor cancellation. + /// + private sealed class WaitingArrayStream : IArrowArrayStream + { + private int _readStarted; + private int _readWasCancelled; + private int _disposed; + + public WaitingArrayStream(Schema schema) + { + Schema = schema; + } + + public Schema Schema { get; } + + public bool ReadStarted => Volatile.Read(ref _readStarted) != 0; + + public bool ReadWasCancelled => Volatile.Read(ref _readWasCancelled) != 0; + + public bool IsDisposed => Volatile.Read(ref _disposed) != 0; + + public async ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + Interlocked.Exchange(ref _readStarted, 1); + try + { + await Task.Delay(Timeout.Infinite, cancellationToken); + } + catch (OperationCanceledException) + { + Interlocked.Exchange(ref _readWasCancelled, 1); + throw; + } + return null; + } + + public void Dispose() + { + Interlocked.Exchange(ref _disposed, 1); + } + } + + /// + /// A consumer written directly against the C callbacks, so tests can drive + /// the producer in ways won't. + /// It records each callback it receives as a string. + /// + private sealed unsafe class RecordingConsumer + { + private readonly long _requestInOnSchema; + private readonly List _events = new List(); + private readonly TaskCompletionSource _released = + new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + private int _inCallback; + private Schema _schema; + + public RecordingConsumer(long requestInOnSchema) + { + _requestInOnSchema = requestInOnSchema; + + Handler = CArrowAsyncDeviceStreamHandler.Create(); +#if NET5_0_OR_GREATER + Handler->on_schema = &OnSchema; + Handler->on_next_task = &OnNextTask; + Handler->on_error = &OnError; + Handler->release = &Release; +#else + Handler->on_schema = Marshal.GetFunctionPointerForDelegate(s_onSchema); + Handler->on_next_task = Marshal.GetFunctionPointerForDelegate(s_onNextTask); + Handler->on_error = Marshal.GetFunctionPointerForDelegate(s_onError); + Handler->release = Marshal.GetFunctionPointerForDelegate(s_release); +#endif + Handler->private_data = (void*)GCHandle.ToIntPtr(GCHandle.Alloc(this)); + } + + public CArrowAsyncDeviceStreamHandler* Handler { get; } + + public bool SawOverlappingCallbacks { get; private set; } + + public IReadOnlyList Events + { + get + { + lock (_events) + { + return _events.ToArray(); + } + } + } + + /// Completes when the producer calls release. + public Task Released => _released.Task; + + private void Record(string evt) + { + lock (_events) + { + _events.Add(evt); + } + } + + private static RecordingConsumer Enter(CArrowAsyncDeviceStreamHandler* handler) + { + var self = (RecordingConsumer)GCHandle.FromIntPtr((IntPtr)handler->private_data).Target; + if (Interlocked.Increment(ref self._inCallback) != 1) + { + self.SawOverlappingCallbacks = true; + } + return self; + } + + private void Exit() + { + Interlocked.Decrement(ref _inCallback); + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static int OnSchema(CArrowAsyncDeviceStreamHandler* handler, CArrowSchema* schema) + { + RecordingConsumer self = Enter(handler); + try + { + // Takes ownership of (and releases) the C schema. + self._schema = CArrowSchemaImporter.ImportSchema(schema); + self.Record("schema"); + + // Calling request() synchronously from on_schema is allowed. + CArrowAsyncProducer* producer = handler->producer; +#if NET5_0_OR_GREATER + producer->request(producer, self._requestInOnSchema); +#else + NativeDelegate.GetDelegateForFunctionPointer(producer->request)(producer, self._requestInOnSchema); +#endif + return 0; + } + catch (Exception) + { + return 131; + } + finally + { + self.Exit(); + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static int OnNextTask(CArrowAsyncDeviceStreamHandler* handler, CArrowAsyncTask* task, byte* metadata) + { + RecordingConsumer self = Enter(handler); + try + { + if (task == null) + { + self.Record("end"); + return 0; + } + + self.Record("task"); + CArrowDeviceArray array = default; +#if NET5_0_OR_GREATER + int errno = task->extract_data(task, &array); +#else + int errno = NativeDelegate.GetDelegateForFunctionPointer(task->extract_data)(task, &array); +#endif + if (errno == 0 && array.array.release != default) + { + // Importing takes ownership of the array; disposing frees it. + CArrowDeviceArrayImporter.ImportRecordBatch(&array, self._schema).Dispose(); + } + return 0; + } + catch (Exception) + { + return 131; + } + finally + { + self.Exit(); + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static void OnError(CArrowAsyncDeviceStreamHandler* handler, int code, byte* message, byte* metadata) + { + RecordingConsumer self = Enter(handler); + try + { + string text = message == null ? "" : Marshal.PtrToStringAnsi((IntPtr)message); + self.Record($"error:{code}:{text}"); + } + finally + { + self.Exit(); + } + } + +#if NET5_0_OR_GREATER + [UnmanagedCallersOnly] +#endif + private static void Release(CArrowAsyncDeviceStreamHandler* handler) + { + RecordingConsumer self = Enter(handler); + GCHandle gch = GCHandle.FromIntPtr((IntPtr)handler->private_data); + try + { + self.Record("release"); + } + finally + { + self.Exit(); + gch.Free(); + CArrowAsyncDeviceStreamHandler.Free(handler); + self._released.TrySetResult(true); + } + } + +#if !NET5_0_OR_GREATER + // Deliberately not the library's own delegate types: on .NET Framework the + // producer must cope with callbacks exported through any delegate type (#491). + private delegate int OnSchemaDelegate(CArrowAsyncDeviceStreamHandler* handler, CArrowSchema* schema); + private delegate int OnNextTaskDelegate(CArrowAsyncDeviceStreamHandler* handler, CArrowAsyncTask* task, byte* metadata); + private delegate void OnErrorDelegate(CArrowAsyncDeviceStreamHandler* handler, int code, byte* message, byte* metadata); + private delegate void ReleaseDelegate(CArrowAsyncDeviceStreamHandler* handler); + + // Kept in static fields so the delegates outlive the function pointers. + private static readonly OnSchemaDelegate s_onSchema = OnSchema; + private static readonly OnNextTaskDelegate s_onNextTask = OnNextTask; + private static readonly OnErrorDelegate s_onError = OnError; + private static readonly ReleaseDelegate s_release = Release; +#endif + } + + private static async Task WaitUntilAsync(Func condition) + { + var deadline = DateTime.UtcNow + TimeSpan.FromSeconds(10); + while (DateTime.UtcNow < deadline) + { + if (condition()) + { + return true; + } + await Task.Delay(5); + } + return condition(); + } + + /// + /// Stream that yields before each batch, giving overlapping readers a chance + /// to interleave, and records the most reads ever in progress at once. + /// + private sealed class YieldingArrayStream : IArrowArrayStream + { + private readonly RecordBatch[] _batches; + private int _next; + private int _active; + private int _maxActive; + + public YieldingArrayStream(Schema schema, RecordBatch[] batches) + { + Schema = schema; + _batches = batches; + } + + public Schema Schema { get; } + + public int MaxConcurrentReads => Volatile.Read(ref _maxActive); + + public async ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + int active = Interlocked.Increment(ref _active); + int max; + while (active > (max = Volatile.Read(ref _maxActive)) && + Interlocked.CompareExchange(ref _maxActive, active, max) != max) + { + } + + try + { + await Task.Yield(); + return _next < _batches.Length ? _batches[_next++] : null; + } + finally + { + Interlocked.Decrement(ref _active); + } + } + + public void Dispose() + { + } + } + + /// + /// Stream that never ends, so only cancellation can stop the producer. + /// + private sealed class EndlessArrayStream : IArrowArrayStream + { + private readonly RecordBatch _batch; + private int _disposed; + + public EndlessArrayStream(RecordBatch batch) + { + _batch = batch; + } + + public Schema Schema => _batch.Schema; + + public bool IsDisposed => Volatile.Read(ref _disposed) != 0; + + public async ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + await Task.Yield(); + // The producer takes ownership of (and disposes) each batch it's given. + return _batch.Clone(); + } + + public void Dispose() + { + Interlocked.Exchange(ref _disposed, 1); + } + } + + /// + /// Stream whose first read waits for a gate before returning its batches. + /// + private sealed class GatedArrayStream : IArrowArrayStream + { + private readonly Task _gate; + private readonly Queue _batches; + + public GatedArrayStream(Schema schema, Task gate, params RecordBatch[] batches) + { + Schema = schema; + _gate = gate; + _batches = new Queue(batches); + } + + public Schema Schema { get; } + + public async ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + await _gate.ConfigureAwait(false); + return _batches.Count > 0 ? _batches.Dequeue() : null; + } + + public void Dispose() + { + } + } + + /// + /// Stream whose schema can't be obtained, standing in for a schema the + /// exporter rejects. + /// + private sealed class ThrowingSchemaArrayStream : IArrowArrayStream + { + private readonly string _message; + private int _disposed; + + public ThrowingSchemaArrayStream(string message) + { + _message = message; + } + + public Schema Schema => throw new NotSupportedException(_message); + + public bool IsDisposed => Volatile.Read(ref _disposed) != 0; + + public ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + throw new InvalidOperationException("Should not be read"); + } + + public void Dispose() + { + Interlocked.Exchange(ref _disposed, 1); + } + } + + /// + /// Simple IArrowArrayStream implementation for testing. + /// + private class TestArrayStream : IArrowArrayStream + { + private readonly Queue _batches; + private int _disposed; + + public TestArrayStream(Schema schema, params RecordBatch[] batches) + { + Schema = schema; + _batches = new Queue(batches); + } + + public Schema Schema { get; } + + public bool IsDisposed => Volatile.Read(ref _disposed) != 0; + + public ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken = default) + { + if (Volatile.Read(ref _disposed) != 0) + { + throw new ObjectDisposedException(nameof(TestArrayStream)); + } + + if (_batches.Count > 0) + { + return new ValueTask(_batches.Dequeue()); + } + return new ValueTask((RecordBatch)null); + } + + public void Dispose() + { + Interlocked.Exchange(ref _disposed, 1); + } + } + } +} diff --git a/test/arrow-go-interop/go.mod b/test/arrow-go-interop/go.mod new file mode 100644 index 00000000..49181ca2 --- /dev/null +++ b/test/arrow-go-interop/go.mod @@ -0,0 +1,32 @@ +// 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. + +module github.com/apache/arrow-dotnet/test/arrow-go-interop + +go 1.25.0 + +require github.com/apache/arrow-go/v18 v18.8.0 + +require ( + github.com/goccy/go-json v0.10.6 // indirect + github.com/google/flatbuffers v25.12.19+incompatible // indirect + github.com/klauspost/compress v1.19.2 // indirect + github.com/klauspost/cpuid/v2 v2.4.0 // indirect + github.com/pierrec/lz4/v4 v4.1.29 // indirect + github.com/zeebo/xxh3 v1.1.0 // indirect + golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect + golang.org/x/sys v0.47.0 // indirect +) diff --git a/test/arrow-go-interop/go.sum b/test/arrow-go-interop/go.sum new file mode 100644 index 00000000..e353981f --- /dev/null +++ b/test/arrow-go-interop/go.sum @@ -0,0 +1,32 @@ +github.com/andybalholm/brotli v1.2.3 h1:8H1qwOkl2LPfjf3YezB90JnCliZb6SInJ/OJkEbA5NQ= +github.com/andybalholm/brotli v1.2.3/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY= +github.com/apache/arrow-go/v18 v18.8.0 h1:BLOzbPv7bxMPgXPacAg6HQjnxupYsZzC4tf+FkqPU/M= +github.com/apache/arrow-go/v18 v18.8.0/go.mod h1:uJCFfCwq0KsxCmsCfQg4ft+LsW+iHYzAXiSDh5ug/8U= +github.com/apache/thrift v0.24.0 h1:zy31L1a49QTNB2bG1BBfMXol3yJrTH975G3pPubQVLQ= +github.com/apache/thrift v0.24.0/go.mod h1:zPt6WxgvTOM6hF92y8C+MkEM5LMxZuk4JcQOiU4Esvs= +github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU= +github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M= +github.com/google/flatbuffers v25.12.19+incompatible h1:haMV2JRRJCe1998HeW/p0X9UaMTK6SDo0ffLn2+DbLs= +github.com/google/flatbuffers v25.12.19+incompatible/go.mod h1:1AeVuKshWv4vARoZatz6mlQ0JxURH0Kv5+zNeJKJCa8= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8= +github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ= +github.com/klauspost/cpuid/v2 v2.4.0 h1:S6Hrbc7+ywsr0r+RLapfGBHfyefhCTwEh3A0tV913Dw= +github.com/klauspost/cpuid/v2 v2.4.0/go.mod h1:19jmZ9mjzoF//ddRSUsv0zfBTJWh3QJh9FNxZTMrGxU= +github.com/pierrec/lz4/v4 v4.1.29 h1:CDQY6qZOLI4DW0Nx6R1vRrifrCeQHnNXkMb0hZWXFjg= +github.com/pierrec/lz4/v4 v4.1.29/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4= +github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE= +github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg= +github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ= +github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0= +github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs= +github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s= +go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= +go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= +golang.org/x/exp v0.0.0-20260112195511-716be5621a96 h1:Z/6YuSHTLOHfNFdb8zVZomZr7cqNgTJvA8+Qz75D8gU= +golang.org/x/exp v0.0.0-20260112195511-716be5621a96/go.mod h1:nzimsREAkjBCIEFtHiYkrJyT+2uy9YZJB7H1k68CXZU= +golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= +golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= +gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= diff --git a/test/arrow-go-interop/main.go b/test/arrow-go-interop/main.go new file mode 100644 index 00000000..d1313035 --- /dev/null +++ b/test/arrow-go-interop/main.go @@ -0,0 +1,359 @@ +// 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. + +// Command arrow-go-interop is built with -buildmode=c-shared and loaded by the +// .NET tests to exercise the Arrow C Async Device Stream Interface against +// arrow-go's independent implementation. +// +// Data enters and leaves this library through the synchronous C Stream +// Interface (ArrowArrayStream), which both libraries already support, so the +// only async hop in each test is the one under test: +// +// .NET sync stream -> [Go async producer] -> .NET async consumer +// .NET async producer -> [Go async consumer] -> .NET sync stream +// +// All exported functions return NULL on success or an error message that the +// caller must free with ArrowGoAsync_FreeError. +package main + +/* +#include +#include +#include "proxy.h" +*/ +import "C" + +import ( + "context" + "errors" + "fmt" + "os" + "runtime/cgo" + "runtime/debug" + "sync" + "sync/atomic" + "time" + "unsafe" + + "github.com/apache/arrow-go/v18/arrow" + "github.com/apache/arrow-go/v18/arrow/array" + "github.com/apache/arrow-go/v18/arrow/cdata" +) + +func main() {} + +// InjectedErrorMessage is the message of the error injected by +// ArrowGoAsync_ProduceFromStream when failAfter is non-negative. +const injectedErrorMessage = "arrow-go-interop: injected producer failure" + +func toCError(err error) *C.char { + if err == nil { + return nil + } + return C.CString(err.Error()) +} + +func recoverToError(err *error) { + if r := recover(); r != nil { + *err = fmt.Errorf("arrow-go-interop: panic: %v", r) + } +} + +//export ArrowGoAsync_FreeError +func ArrowGoAsync_FreeError(msg *C.char) { + C.free(unsafe.Pointer(msg)) +} + +// ArrowGoAsync_SetCrashOutput makes the Go runtime also write fatal errors +// (unrecovered panics in callbacks, etc.) to the given file. The test host +// usually swallows stderr, so otherwise a Go crash leaves no trace. +// +//export ArrowGoAsync_SetCrashOutput +func ArrowGoAsync_SetCrashOutput(path *C.char) (cErr *C.char) { + f, err := os.OpenFile(C.GoString(path), os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644) + if err != nil { + return toCError(err) + } + defer f.Close() + return toCError(debug.SetCrashOutput(f, debug.CrashOptions{})) +} + +// ArrowGoAsync_ProduceFromStream reads every batch from the given +// ArrowArrayStream and pushes it through the given ArrowAsyncDeviceStreamHandler +// using arrow-go's async producer. It blocks until the stream has been fully +// produced and the handler has been released. +// +// If failAfter is non-negative, the producer reports an error to the handler +// after delivering that many batches instead of continuing. +// +//export ArrowGoAsync_ProduceFromStream +func ArrowGoAsync_ProduceFromStream(source unsafe.Pointer, handler unsafe.Pointer, failAfter C.int64_t) (cErr *C.char) { + var err error + defer func() { cErr = toCError(err) }() + defer recoverToError(&err) + + err = produceFromStream( + (*cdata.CArrowArrayStream)(source), + (*cdata.CArrowAsyncDeviceStreamHandler)(handler), + int64(failAfter)) + return +} + +func produceFromStream(source *cdata.CArrowArrayStream, handler *cdata.CArrowAsyncDeviceStreamHandler, failAfter int64) error { + imported, err := cdata.ImportCRecordReader(source, nil) + if err != nil { + return fmt.Errorf("importing source stream: %w", err) + } + reader, ok := imported.(array.RecordReader) + if !ok { + return errors.New("imported source stream is not an array.RecordReader") + } + defer reader.Release() + + schema := reader.Schema() + if schema == nil { + if reader.Err() != nil { + return fmt.Errorf("reading source schema: %w", reader.Err()) + } + return errors.New("source stream has no schema") + } + + messages := make(chan arrowMessage) + stop := make(chan struct{}) + go func() { + defer close(messages) + var sent int64 + for reader.Next() { + if failAfter >= 0 && sent == failAfter { + select { + case messages <- arrowMessage{Err: errors.New(injectedErrorMessage)}: + case <-stop: + } + return + } + rec := reader.RecordBatch() + // The reader releases the current batch on the next call to Next; + // the async producer releases it after extract_data. + rec.Retain() + select { + case messages <- arrowMessage{Record: rec}: + sent++ + case <-stop: + rec.Release() + return + } + } + if reader.Err() != nil { + select { + case messages <- arrowMessage{Err: reader.Err()}: + case <-stop: + } + } + }() + + err = cdata.ExportAsyncRecordBatchStream(schema, messages, handler) + + // Unblock and drain the pump goroutine in case the producer stopped early. + close(stop) + for msg := range messages { + if msg.Record != nil { + msg.Record.Release() + } + } + return err +} + +type arrowMessage = cdata.RecordMessage + +// consumer holds the state of one arrow-go async consumer created by +// ArrowGoAsync_ConsumerCreate. +type consumer struct { + ctx context.Context + cancel context.CancelFunc + ch <-chan cdata.AsyncRecordBatchStream + + // Sits between the .NET producer and arrow-go; see proxy.h. + proxy *C.struct_InteropProxy + + // Closed once arrow-go can no longer touch the proxy: its task goroutine + // has exited (its record channel closed) or was never started. + goDone chan struct{} + goDoneOnce sync.Once +} + +func (c *consumer) markGoDone() { + c.goDoneOnce.Do(func() { close(c.goDone) }) +} + +// ArrowGoAsync_ConsumerCreate populates the given ArrowAsyncDeviceStreamHandler +// so that it feeds arrow-go's async consumer. queueSize is the number of batches +// arrow-go requests up front; it then requests one more for each batch it +// consumes. Returns an opaque consumer id in *outId, which must eventually be +// passed to ArrowGoAsync_ConsumerFree. +// +//export ArrowGoAsync_ConsumerCreate +func ArrowGoAsync_ConsumerCreate(handler unsafe.Pointer, queueSize C.uint64_t, outId *C.uintptr_t) (cErr *C.char) { + var err error + defer func() { cErr = toCError(err) }() + defer recoverToError(&err) + + if queueSize == 0 { + err = errors.New("queueSize must be positive") + return + } + + proxy := C.InteropProxy_Create((*C.struct_ArrowAsyncDeviceStreamHandler)(handler)) + if proxy == nil { + err = errors.New("could not allocate proxy") + return + } + inner := unsafe.Pointer(C.InteropProxy_Inner(proxy)) + + ctx, cancel := context.WithCancel(context.Background()) + ch := cdata.CreateAsyncDeviceStreamHandler(ctx, uint64(queueSize), (*cdata.CArrowAsyncDeviceStreamHandler)(inner)) + c := &consumer{ctx: ctx, cancel: cancel, ch: ch, proxy: proxy, goDone: make(chan struct{})} + *outId = C.uintptr_t(cgo.NewHandle(c)) + return +} + +// ArrowGoAsync_ConsumerToStream blocks until the producer has delivered the +// schema (or failed before doing so), then exports the consumed batches as a +// synchronous ArrowArrayStream into out. Errors the producer reports after the +// schema surface as errors from the exported stream's get_next. +// +//export ArrowGoAsync_ConsumerToStream +func ArrowGoAsync_ConsumerToStream(id C.uintptr_t, out unsafe.Pointer) (cErr *C.char) { + var err error + defer func() { cErr = toCError(err) }() + defer recoverToError(&err) + + c := cgo.Handle(id).Value().(*consumer) + stream, ok := <-c.ch + if !ok { + c.markGoDone() + err = errors.New("async consumer closed without delivering a stream") + return + } + if stream.Err != nil { + // arrow-go only starts its task goroutine after a successful on_schema. + c.markGoDone() + err = stream.Err + return + } + + rdr := &channelReader{schema: stream.Schema, stream: stream.Stream, cancel: c.cancel, onClosed: c.markGoDone} + rdr.refCount.Store(1) + cdata.ExportRecordReader(rdr, (*cdata.CArrowArrayStream)(out)) + return +} + +// ArrowGoAsync_ConsumerCancel asks the producer to stop by cancelling the +// consumer's context; arrow-go then calls the producer's cancel callback. +// +//export ArrowGoAsync_ConsumerCancel +func ArrowGoAsync_ConsumerCancel(id C.uintptr_t) { + cgo.Handle(id).Value().(*consumer).cancel() +} + +// ArrowGoAsync_ConsumerFree releases the consumer id. It does not release the +// handler; that is the producer's job. The proxy is freed in the background +// once the producer has released the handler and arrow-go is done with it; if +// either never happens (a bug the tests would report), it is leaked rather +// than freed while still in use. +// +//export ArrowGoAsync_ConsumerFree +func ArrowGoAsync_ConsumerFree(id C.uintptr_t) { + h := cgo.Handle(id) + c := h.Value().(*consumer) + h.Delete() + c.cancel() + + go func() { + <-c.goDone + for C.InteropProxy_IsReleased(c.proxy) == 0 { + time.Sleep(10 * time.Millisecond) + } + C.InteropProxy_Free(c.proxy) + }() +} + +// channelReader adapts arrow-go's consumed batch channel to array.RecordReader +// so it can be exported as a synchronous ArrowArrayStream. +type channelReader struct { + refCount atomic.Int64 + schema *arrow.Schema + stream <-chan cdata.RecordMessage + cancel context.CancelFunc + onClosed func() // called once the stream channel is seen closed + cur arrow.RecordBatch + err error + once sync.Once +} + +func (r *channelReader) Retain() { r.refCount.Add(1) } + +func (r *channelReader) Release() { + if r.refCount.Add(-1) != 0 { + return + } + r.once.Do(func() { + r.releaseCurrent() + // Stop the producer if the stream wasn't read to the end, and release + // anything still queued so arrow-go's goroutines can exit. + r.cancel() + go func() { + for msg := range r.stream { + if msg.Record != nil { + msg.Record.Release() + } + } + r.onClosed() + }() + }) +} + +func (r *channelReader) releaseCurrent() { + if r.cur != nil { + r.cur.Release() + r.cur = nil + } +} + +func (r *channelReader) Schema() *arrow.Schema { return r.schema } + +func (r *channelReader) Next() bool { + r.releaseCurrent() + if r.err != nil { + return false + } + msg, ok := <-r.stream + if !ok { + r.onClosed() + return false + } + if msg.Err != nil { + r.err = msg.Err + return false + } + r.cur = msg.Record + return true +} + +func (r *channelReader) RecordBatch() arrow.RecordBatch { return r.cur } + +func (r *channelReader) Record() arrow.RecordBatch { return r.cur } + +func (r *channelReader) Err() error { return r.err } diff --git a/test/arrow-go-interop/proxy.c b/test/arrow-go-interop/proxy.c new file mode 100644 index 00000000..6cc8b722 --- /dev/null +++ b/test/arrow-go-interop/proxy.c @@ -0,0 +1,183 @@ +// 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. + +// See proxy.h for why this exists. + +#include "proxy.h" + +#include +#include + +struct InteropProxy { + struct ArrowAsyncDeviceStreamHandler* outer; + struct ArrowAsyncDeviceStreamHandler inner; + struct ArrowAsyncProducer producer; + + // Guards real_producer and released. Held while forwarding request/cancel, + // so release can't proceed (and the real producer be freed) mid-call. + // released means outer_release has finished with the proxy, not just begun. A + // spinlock keeps this free of threading-library dependencies; critical + // sections are short because request/cancel must not block or call back. + volatile char lock; + struct ArrowAsyncProducer* real_producer; + int released; + + // Set if arrow-go's on_schema failed; see outer_release. Only touched by the + // producer's thread, which calls on_schema and release in order. + int inner_schema_failed; +}; + +static void proxy_lock(struct InteropProxy* p) { + while (__atomic_test_and_set(&p->lock, __ATOMIC_ACQUIRE)) { + } +} + +static void proxy_unlock(struct InteropProxy* p) { + __atomic_clear(&p->lock, __ATOMIC_RELEASE); +} + +static struct InteropProxy* from_outer(struct ArrowAsyncDeviceStreamHandler* self) { + return (struct InteropProxy*)self->private_data; +} + +// ---- proxy producer, called by arrow-go ---- +// +// These hold the (non-reentrant) spinlock while calling into the real producer, +// and outer_release takes it too. That relies on the real producer never calling +// release synchronously from request or cancel; if it did, outer_release would +// spin forever on the lock its own thread holds. Apache.Arrow's producer never +// does: request and cancel only update state, and release always happens on the +// produce loop's thread. + +static void proxy_request(struct ArrowAsyncProducer* self, int64_t n) { + struct InteropProxy* p = (struct InteropProxy*)self->private_data; + proxy_lock(p); + // real_producer is cleared as soon as release starts. + if (p->real_producer != NULL) { + p->real_producer->request(p->real_producer, n); + } + proxy_unlock(p); +} + +static void proxy_cancel(struct ArrowAsyncProducer* self) { + struct InteropProxy* p = (struct InteropProxy*)self->private_data; + proxy_lock(p); + if (p->real_producer != NULL) { + p->real_producer->cancel(p->real_producer); + } + proxy_unlock(p); +} + +// ---- outer handler, called by the .NET producer; forwards to arrow-go ---- + +static int outer_on_schema(struct ArrowAsyncDeviceStreamHandler* self, + struct ArrowSchema* schema) { + struct InteropProxy* p = from_outer(self); + + proxy_lock(p); + p->real_producer = self->producer; + proxy_unlock(p); + + p->producer.device_type = self->producer->device_type; + p->producer.additional_metadata = self->producer->additional_metadata; + p->inner.producer = &p->producer; + + // Not under the lock: arrow-go calls request() synchronously from on_schema. + int status = p->inner.on_schema(&p->inner, schema); + if (status != 0) { + p->inner_schema_failed = 1; + } + return status; +} + +static int outer_on_next_task(struct ArrowAsyncDeviceStreamHandler* self, + struct ArrowAsyncTask* task, const char* metadata) { + struct InteropProxy* p = from_outer(self); + return p->inner.on_next_task(&p->inner, task, metadata); +} + +static void outer_on_error(struct ArrowAsyncDeviceStreamHandler* self, int code, + const char* message, const char* metadata) { + struct InteropProxy* p = from_outer(self); + p->inner.on_error(&p->inner, code, message, metadata); +} + +static void outer_release(struct ArrowAsyncDeviceStreamHandler* self) { + struct InteropProxy* p = from_outer(self); + + // The real producer may be freed once this returns: stop forwarding to it now. + proxy_lock(p); + p->real_producer = NULL; + proxy_unlock(p); + + // arrow-go keeps writing to the inner handler (which lives in the proxy) after + // its task goroutine may have exited, so the proxy must not be reported as + // released until this returns. + // + // WORKAROUND: when arrow-go's on_schema fails, it frees its handler state but + // leaves its release callback installed, and that callback then reads the freed + // state and panics. The spec has the producer call release after a failed + // on_schema, so don't forward it in that case; arrow-go has already cleaned up. + // Remove once arrow-go is fixed: https://github.com/apache/arrow-go/issues/1573 + if (p->inner.release != NULL && !p->inner_schema_failed) { + p->inner.release(&p->inner); + } + + self->private_data = NULL; + + // Publish completion only after the last access to each struct: once released + // is set, ArrowGoAsync_ConsumerFree may free the proxy, and once self->release + // is cleared, the test may free the outer handler. + proxy_lock(p); + p->released = 1; + proxy_unlock(p); + __atomic_store_n(&self->release, NULL, __ATOMIC_RELEASE); +} + +// ---- lifetime ---- + +struct InteropProxy* InteropProxy_Create(struct ArrowAsyncDeviceStreamHandler* outer) { + struct InteropProxy* p = (struct InteropProxy*)calloc(1, sizeof(struct InteropProxy)); + if (p == NULL) { + return NULL; + } + + p->outer = outer; + p->producer.request = proxy_request; + p->producer.cancel = proxy_cancel; + p->producer.private_data = p; + + memset(outer, 0, sizeof(*outer)); + outer->on_schema = outer_on_schema; + outer->on_next_task = outer_on_next_task; + outer->on_error = outer_on_error; + outer->release = outer_release; + outer->private_data = p; + return p; +} + +struct ArrowAsyncDeviceStreamHandler* InteropProxy_Inner(struct InteropProxy* proxy) { + return &proxy->inner; +} + +int InteropProxy_IsReleased(struct InteropProxy* proxy) { + proxy_lock(proxy); + int released = proxy->released; + proxy_unlock(proxy); + return released; +} + +void InteropProxy_Free(struct InteropProxy* proxy) { free(proxy); } diff --git a/test/arrow-go-interop/proxy.h b/test/arrow-go-interop/proxy.h new file mode 100644 index 00000000..97470542 --- /dev/null +++ b/test/arrow-go-interop/proxy.h @@ -0,0 +1,85 @@ +// 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. + +// WORKAROUND for an arrow-go (v18.8.0) consumer bug: after the producer calls +// release on the handler, arrow-go's task goroutine keeps draining tasks that +// were already queued and calls request(1) on the producer for each one. The +// spec only requires the producer to stay valid until release, so a conforming +// producer (like Apache.Arrow's) may already have freed it: use-after-free. +// +// The proxy sits between the .NET producer and arrow-go's consumer: +// +// .NET producer --> outer handler (proxy callbacks) --> inner handler (arrow-go) +// arrow-go --> proxy producer (owned here) --> real .NET producer +// +// The proxy producer forwards request/cancel to the real producer only until the +// outer handler is released, and stays allocated until arrow-go is done with it. +// Remove this once arrow-go is fixed: https://github.com/apache/arrow-go/issues/1572 +// +// The proxy also works around a second arrow-go (v18.8.0) bug: after a failed +// on_schema, arrow-go's own release callback uses state it has already freed, so +// the proxy doesn't forward release in that case. See outer_release and +// https://github.com/apache/arrow-go/issues/1573 + +#pragma once + +#include + +#ifndef ARROW_C_ASYNC_STREAM_INTERFACE +#define ARROW_C_ASYNC_STREAM_INTERFACE + +// Layouts from the Arrow C Device Data Interface specification. +typedef int32_t ArrowDeviceType; + +struct ArrowSchema; +struct ArrowAsyncTask; + +struct ArrowAsyncProducer { + ArrowDeviceType device_type; + void (*request)(struct ArrowAsyncProducer* self, int64_t n); + void (*cancel)(struct ArrowAsyncProducer* self); + const char* additional_metadata; + void* private_data; +}; + +struct ArrowAsyncDeviceStreamHandler { + int (*on_schema)(struct ArrowAsyncDeviceStreamHandler* self, + struct ArrowSchema* stream_schema); + int (*on_next_task)(struct ArrowAsyncDeviceStreamHandler* self, + struct ArrowAsyncTask* task, const char* metadata); + void (*on_error)(struct ArrowAsyncDeviceStreamHandler* self, int code, + const char* message, const char* metadata); + void (*release)(struct ArrowAsyncDeviceStreamHandler* self); + struct ArrowAsyncProducer* producer; + void* private_data; +}; + +#endif // ARROW_C_ASYNC_STREAM_INTERFACE + +struct InteropProxy; + +// Install the proxy callbacks on outer (the handler given to the .NET producer) +// and return the proxy. Pass InteropProxy_Inner to arrow-go's consumer. +struct InteropProxy* InteropProxy_Create(struct ArrowAsyncDeviceStreamHandler* outer); + +struct ArrowAsyncDeviceStreamHandler* InteropProxy_Inner(struct InteropProxy* proxy); + +// Whether the producer has released the outer handler. +int InteropProxy_IsReleased(struct InteropProxy* proxy); + +// Free the proxy. Only call once the outer handler has been released and +// arrow-go's consumer goroutine has exited. +void InteropProxy_Free(struct InteropProxy* proxy);