Skip to content

Commit 05f0d3d

Browse files
committed
feat(cancel): add CancellationToken with collect/executeStream overloads
Tokens are session-allocated, fired from any thread, and abort the next cooperative poll point of the targeted call. Pre-stream cancellations surface as `java.util.concurrent.CancellationException`; mid-stream cancellations from `executeStream(..., token)` surface from `ArrowReader.loadNextBatch` as `IOException` whose message contains `"query cancelled"` (the Arrow C-data wrapper hides the typed signal). Native handles are opaque registry IDs guarded by an `AtomicLong` on the Java side, so concurrent close + cancel is safe: the worst race outcome is a clean `IllegalStateException` from a missing-ID lookup rather than a use-after-free of a freed `Box`.
1 parent fe4414a commit 05f0d3d

10 files changed

Lines changed: 958 additions & 15 deletions

File tree

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.apache.datafusion;
21+
22+
import java.util.concurrent.CancellationException;
23+
import java.util.concurrent.atomic.AtomicLong;
24+
25+
/**
26+
* A handle that signals an in-flight {@link
27+
* DataFrame#collect(org.apache.arrow.memory.BufferAllocator, CancellationToken)} or {@link
28+
* DataFrame#executeStream(org.apache.arrow.memory.BufferAllocator, CancellationToken)} to abort.
29+
*
30+
* <p>Allocate via {@link SessionContext#newCancellationToken()}, pass to the desired call from one
31+
* thread, and invoke {@link #cancel()} from another. The running query aborts at its next
32+
* cooperative poll point. The exception type depends on the call site: {@code collect(..., token)}
33+
* and pre-stream cancellation in {@code executeStream(..., token)} surface {@link
34+
* CancellationException}; mid-stream cancellation in {@code executeStream} surfaces from {@link
35+
* org.apache.arrow.vector.ipc.ArrowReader#loadNextBatch} as a {@link java.io.IOException} whose
36+
* message contains {@code "query cancelled"} (the Arrow C-data wrapper hides the typed signal). See
37+
* the {@code executeStream} Javadoc for the full contract.
38+
*
39+
* <p>The token is not bound to any particular DataFrame; the same token may be passed to several
40+
* concurrent {@code collect} / {@code executeStream} calls, and {@link #cancel()} fires all of them
41+
* at once. Once cancelled, {@link #isCancelled()} returns {@code true} permanently — to "reset",
42+
* allocate a fresh token. This matches the underlying {@code tokio_util::sync::CancellationToken}
43+
* contract.
44+
*
45+
* <p>Instances are safe to call {@link #cancel()} / {@link #isCancelled()} on from any thread, and
46+
* must be {@link #close() closed} to release the native handle. {@code close()} is idempotent and a
47+
* no-op once invoked.
48+
*/
49+
public final class CancellationToken implements AutoCloseable {
50+
static {
51+
NativeLibraryLoader.loadLibrary();
52+
}
53+
54+
// Atomic so concurrent close + cancel/isCancelled/handle-pass-to-JNI cannot
55+
// double-free or pass a stale handle to the native side. Reads observe either
56+
// a live registry id or the post-close 0 sentinel; the close path uses
57+
// getAndSet so only one thread can issue closeToken.
58+
private final AtomicLong nativeHandle;
59+
60+
CancellationToken(long nativeHandle) {
61+
if (nativeHandle == 0) {
62+
throw new IllegalArgumentException("CancellationToken native handle is null");
63+
}
64+
this.nativeHandle = new AtomicLong(nativeHandle);
65+
}
66+
67+
/**
68+
* The internal native handle, or {@code 0} if this token is closed. Package-private so {@link
69+
* DataFrame} can pass it across JNI. The native side's registry lookup gracefully rejects a
70+
* closed handle, so a race between {@code handle()} and {@link #close()} is bounded to a clean
71+
* "closed" error rather than a use-after-free.
72+
*/
73+
long handle() {
74+
return nativeHandle.get();
75+
}
76+
77+
/**
78+
* Signal the token. Any {@code collect} or {@code executeStream} call that received this token
79+
* aborts at its next poll point. The thrown exception type depends on whether the cancel reaches
80+
* the call before or after the JNI call returns — see the class-level Javadoc. Idempotent:
81+
* subsequent calls are no-ops.
82+
*
83+
* @throws IllegalStateException if this token is closed.
84+
*/
85+
public void cancel() {
86+
long h = nativeHandle.get();
87+
if (h == 0) {
88+
throw new IllegalStateException("CancellationToken is closed");
89+
}
90+
cancelToken(h);
91+
}
92+
93+
/**
94+
* @return {@code true} if {@link #cancel()} has been invoked on this token, {@code false}
95+
* otherwise. Non-blocking.
96+
* @throws IllegalStateException if this token is closed.
97+
*/
98+
public boolean isCancelled() {
99+
long h = nativeHandle.get();
100+
if (h == 0) {
101+
throw new IllegalStateException("CancellationToken is closed");
102+
}
103+
return isCancelledToken(h);
104+
}
105+
106+
/**
107+
* Release the native handle. Idempotent. After {@code close()}, {@link #cancel()} and {@link
108+
* #isCancelled()} throw {@link IllegalStateException}. Closing a token that already fired is
109+
* harmless and does not cancel anything else; queries that already received the cancel signal
110+
* remain aborted.
111+
*/
112+
@Override
113+
public void close() {
114+
long h = nativeHandle.getAndSet(0L);
115+
if (h != 0) {
116+
closeToken(h);
117+
}
118+
}
119+
120+
private static native void cancelToken(long handle);
121+
122+
private static native boolean isCancelledToken(long handle);
123+
124+
private static native void closeToken(long handle);
125+
}

‎core/src/main/java/org/apache/datafusion/DataFrame.java‎

Lines changed: 69 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,14 +61,29 @@ public final class DataFrame implements AutoCloseable {
6161
* {@link #executeStream(BufferAllocator)} for analytics-scale queries.
6262
*/
6363
public ArrowReader collect(BufferAllocator allocator) {
64+
return collect(allocator, null);
65+
}
66+
67+
/**
68+
* Execute the plan with cooperative cancellation. Identical to {@link #collect(BufferAllocator)}
69+
* except that {@link CancellationToken#cancel()} on {@code token} from another thread aborts the
70+
* call with a {@link java.util.concurrent.CancellationException} at the next poll point.
71+
*
72+
* <p>{@code token} may be {@code null}, in which case this overload behaves exactly like the
73+
* single-argument form.
74+
*
75+
* @throws java.util.concurrent.CancellationException if the token is fired during the call.
76+
*/
77+
public ArrowReader collect(BufferAllocator allocator, CancellationToken token) {
6478
if (nativeHandle == 0) {
6579
throw new IllegalStateException("DataFrame is closed or already collected");
6680
}
81+
long tokenHandle = resolveTokenHandle(token);
6782
ArrowArrayStream stream = ArrowArrayStream.allocateNew(allocator);
6883
long handle = nativeHandle;
6984
nativeHandle = 0;
7085
try {
71-
collectDataFrame(handle, stream.memoryAddress());
86+
collectDataFrame(handle, stream.memoryAddress(), tokenHandle);
7287
return Data.importArrayStream(allocator, stream);
7388
} catch (Throwable e) {
7489
stream.close();
@@ -91,21 +106,70 @@ public ArrowReader collect(BufferAllocator allocator) {
91106
* use this method.
92107
*/
93108
public ArrowReader executeStream(BufferAllocator allocator) {
109+
return executeStream(allocator, null);
110+
}
111+
112+
/**
113+
* Execute the plan as a streaming reader with cooperative cancellation. Identical to {@link
114+
* #executeStream(BufferAllocator)} except that the returned reader holds the supplied {@code
115+
* token} for its full lifetime: firing the token from another thread aborts the next {@link
116+
* ArrowReader#loadNextBatch} call.
117+
*
118+
* <p>{@code token} may be {@code null}, in which case this overload behaves exactly like the
119+
* single-argument form.
120+
*
121+
* <p><b>Cancellation surface (read carefully).</b> The exception type depends on <em>when</em>
122+
* the cancel fires, because the Arrow C-data stream layer wraps any underlying error before it
123+
* reaches Java:
124+
*
125+
* <ul>
126+
* <li>If the token is fired <b>before</b> the stream is established (e.g., the token was
127+
* already cancelled at call time, or fires during plan compilation), this method throws
128+
* {@link java.util.concurrent.CancellationException}.
129+
* <li>If the token fires <b>after</b> {@code executeStream} returns, the next {@link
130+
* ArrowReader#loadNextBatch} throws {@link java.io.IOException} whose message contains the
131+
* string {@code "query cancelled"}. Callers that need to distinguish cancellation from real
132+
* I/O failures must match on the message until a typed surface lands as a follow-up.
133+
* </ul>
134+
*
135+
* @throws java.util.concurrent.CancellationException if the token fires before the stream is
136+
* established.
137+
*/
138+
public ArrowReader executeStream(BufferAllocator allocator, CancellationToken token) {
94139
if (nativeHandle == 0) {
95140
throw new IllegalStateException("DataFrame is closed or already collected");
96141
}
142+
long tokenHandle = resolveTokenHandle(token);
97143
ArrowArrayStream stream = ArrowArrayStream.allocateNew(allocator);
98144
long handle = nativeHandle;
99145
nativeHandle = 0;
100146
try {
101-
executeStreamDataFrame(handle, stream.memoryAddress());
147+
executeStreamDataFrame(handle, stream.memoryAddress(), tokenHandle);
102148
return Data.importArrayStream(allocator, stream);
103149
} catch (Throwable e) {
104150
stream.close();
105151
throw e;
106152
}
107153
}
108154

155+
/**
156+
* A {@code null} token disables cancellation; a non-null but already-closed token is rejected
157+
* with {@link IllegalStateException}, matching how {@link CancellationToken#cancel()} and {@link
158+
* CancellationToken#isCancelled()} behave on a closed token. Without this check, premature {@code
159+
* close()} on a token would silently fall back to an uncancellable call, which is hard to
160+
* diagnose.
161+
*/
162+
private static long resolveTokenHandle(CancellationToken token) {
163+
if (token == null) {
164+
return 0L;
165+
}
166+
long handle = token.handle();
167+
if (handle == 0L) {
168+
throw new IllegalStateException("CancellationToken is closed");
169+
}
170+
return handle;
171+
}
172+
109173
/** Execute the plan and return the number of rows. */
110174
public long count() {
111175
if (nativeHandle == 0) {
@@ -326,9 +390,10 @@ public void close() {
326390
}
327391
}
328392

329-
private static native void collectDataFrame(long handle, long ffiStreamAddr);
393+
private static native void collectDataFrame(long handle, long ffiStreamAddr, long tokenHandle);
330394

331-
private static native void executeStreamDataFrame(long handle, long ffiStreamAddr);
395+
private static native void executeStreamDataFrame(
396+
long handle, long ffiStreamAddr, long tokenHandle);
332397

333398
private static native void closeDataFrame(long handle);
334399

‎core/src/main/java/org/apache/datafusion/SessionContext.java‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -426,6 +426,24 @@ public DataFrame readAvro(String path, AvroReadOptions options) {
426426
return new DataFrame(dfHandle);
427427
}
428428

429+
/**
430+
* Allocate a fresh {@link CancellationToken}. Pass it to {@link
431+
* DataFrame#collect(BufferAllocator, CancellationToken)} or {@link
432+
* DataFrame#executeStream(BufferAllocator, CancellationToken)} to make a query cancellable; fire
433+
* the token from any thread to abort the in-flight call.
434+
*
435+
* <p>The same token may be reused across multiple concurrent calls; firing it cancels them all.
436+
* Once fired, a token stays cancelled — allocate a fresh token for the next query.
437+
*
438+
* <p>The token is independent of this {@link SessionContext}: closing the context does not
439+
* implicitly close outstanding tokens, and a token outliving its session is harmless (it just has
440+
* nothing left to cancel). Always close tokens in their own try-with-resources to release the
441+
* native handle.
442+
*/
443+
public CancellationToken newCancellationToken() {
444+
return new CancellationToken(createCancellationToken());
445+
}
446+
429447
/**
430448
* Register a Java-implemented scalar UDF. After registration, the function can be invoked by SQL
431449
* via the UDF's name or referenced in DataFusion plans deserialised with {@link #fromProto}.
@@ -523,4 +541,6 @@ private static native long readJsonWithOptions(
523541

524542
private static native void registerScalarUdf(
525543
long handle, String name, byte[] signatureSchemaBytes, byte volatility, ScalarFunction impl);
544+
545+
private static native long createCancellationToken();
526546
}

0 commit comments

Comments
 (0)