模块 wjybxx.commons.concurrent

程序包 cn.wjybxx.concurrent

类 CancelTokenSource

java.lang.Object

cn.wjybxx.concurrent.CancelTokenSource

所有已实现的接口:

ICancelToken, ICancelTokenSource

public final class CancelTokenSource
extends Object
implements ICancelTokenSource

取消令牌源由任务的创建者（发起者）持有，具备取消权限。

实现说明

这里的实现是Promise的翻版，但不同的是：取消令牌需要支持删除监听，而且取消令牌存在频繁增删监听的情况！ 由于实现高效且安全的删除并不容易，这里暂时采用延迟删除的方案。

作者:

wjybxx date - 2024/1/8

字段概要

从接口继承的字段 cn.wjybxx.concurrent.ICancelToken

NONE

构造器概要

构造器

构造器	说明
CancelTokenSource()
CancelTokenSource(int code)

方法概要

修饰符和类型	方法	说明
ICancelToken	asReadonly()	返回一个只读的ICancelToken试图，返回的实例会在当前Token被取消时取消。
boolean	canBeCancelled()	当前token是否可以进入取消状态
int	cancel()	使用默认原因取消
int	cancel(boolean mayInterruptIfRunning)	该方法主要用于兼容JDK
int	cancel(int cancelCode)	将Token置为取消状态
void	cancelAfter(int cancelCode, long millisecondsDelay)	在一段时间后发送取消命令
void	cancelAfter(int cancelCode, long delay, TimeUnit timeUnit)	在一段时间后发送取消命令 (将由默认的调度器调度)
void	cancelAfter(int cancelCode, long delay, TimeUnit timeUnit, ScheduledExecutorService executor)
int	cancelCode()	取消码 1.
void	checkCancel()	检测取消信号 如果收到取消信号，则抛出CancellationException
int	degree()	取消的紧急程度
boolean	isCancelling()	是否已收到取消信号 任务的执行者将持有该令牌，在调度任务前会检测取消信号；如果任务已经开始，则由用户的任务自身检测取消和中断信号。
boolean	isInterruptible()	取消指令中是否要求了中断线程
boolean	isWithoutRemove()	取消指令中是否要求了无需删除
CancelTokenSource	newInstance()
CancelTokenSource	newInstance(boolean copyCode)	创建一个同类型实例。
int	reason()	取消的原因 (1~10为底层使用，10以上为用户自定义)T
IRegistration	thenAccept(BiConsumer<? super ICancelToken,Object> action, Object ctx)
IRegistration	thenAccept(BiConsumer<? super ICancelToken,Object> action, Object ctx, int options)
IRegistration	thenAccept(Consumer<? super ICancelToken> action)
IRegistration	thenAccept(Consumer<? super ICancelToken> action, int options)	添加的action将在Context收到取消信号时执行 1.如果已收到取消请求，则给定的action会立即执行。
IRegistration	thenAcceptAsync(Executor executor, BiConsumer<? super ICancelToken,Object> action, Object ctx)
IRegistration	thenAcceptAsync(Executor executor, BiConsumer<? super ICancelToken,Object> action, Object ctx, int options)
IRegistration	thenAcceptAsync(Executor executor, Consumer<? super ICancelToken> action)
IRegistration	thenAcceptAsync(Executor executor, Consumer<? super ICancelToken> action, int options)
IRegistration	thenNotify(CancelTokenListener action)
IRegistration	thenNotify(CancelTokenListener action, int options)	添加一个特定类型的监听器 (用于特殊需求时避免额外的闭包 - task经常需要监听取消令牌)
IRegistration	thenNotifyAsync(Executor executor, CancelTokenListener action)
IRegistration	thenNotifyAsync(Executor executor, CancelTokenListener action, int options)
IRegistration	thenRun(Runnable action)
IRegistration	thenRun(Runnable action, int options)
IRegistration	thenRun(Consumer<Object> action, Object ctx)
IRegistration	thenRun(Consumer<Object> action, Object ctx, int options)
IRegistration	thenRunAsync(Executor executor, Runnable action)
IRegistration	thenRunAsync(Executor executor, Runnable action, int options)
IRegistration	thenRunAsync(Executor executor, Consumer<Object> action, Object ctx)
IRegistration	thenRunAsync(Executor executor, Consumer<Object> action, Object ctx, int options)
IRegistration	thenTransferTo(ICancelTokenSource child)
IRegistration	thenTransferTo(ICancelTokenSource child, int options)	该接口用于方便构建子上下文 1.子token会在当前token进入取消状态时被取消 2.该接口本质是一个快捷方法，但允许子类优化
IRegistration	thenTransferToAsync(Executor executor, ICancelTokenSource child)
IRegistration	thenTransferToAsync(Executor executor, ICancelTokenSource child, int options)

从类继承的方法 java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造器详细资料

CancelTokenSource

public CancelTokenSource()

CancelTokenSource

public CancelTokenSource(int code)

方法详细资料

asReadonly

public ICancelToken asReadonly()

从接口复制的说明: ICancelToken

返回一个只读的ICancelToken试图，返回的实例会在当前Token被取消时取消。 其作用类似IFuture.asReadonly()

指定者:

asReadonly 在接口中 ICancelToken

canBeCancelled

public boolean canBeCancelled()

从接口复制的说明: ICancelToken

当前token是否可以进入取消状态

指定者:

canBeCancelled 在接口中 ICancelToken

返回:

如果当前token可以进入取消状态则返回true

newInstance

public CancelTokenSource newInstance(boolean copyCode)

从接口复制的说明: ICancelTokenSource

创建一个同类型实例。 1.原型对象，避免具体类型依赖。 2.默认情况下，其它上下文应当拷贝。

指定者:

newInstance 在接口中 ICancelTokenSource

参数:

copyCode - 是否拷贝当前取消码

返回:

取消令牌

newInstance

public CancelTokenSource newInstance()

指定者:

newInstance 在接口中 ICancelTokenSource

cancel

public int cancel(int cancelCode)

将Token置为取消状态

指定者:

cancel 在接口中 ICancelTokenSource

参数:

cancelCode - 取消码；reason部分需大于0；辅助类CancelCodeBuilder

返回:

如果Token已被取消，则返回旧值（大于0）；如果Token尚未被取消，则将Token更新为取消状态，并返回0。

抛出:

IllegalArgumentException - 如果code小于等于0；或reason部分为0

UnsupportedOperationException - 如果context是只读的

cancel

public int cancel()

使用默认原因取消

指定者:

cancel 在接口中 ICancelTokenSource

cancel

public int cancel(boolean mayInterruptIfRunning)

该方法主要用于兼容JDK

指定者:

cancel 在接口中 ICancelTokenSource

参数:

mayInterruptIfRunning - 是否可以中断目标线程；注意该参数由任务自身处理，且任务监听了取消信号才有用

cancelAfter

public void cancelAfter(int cancelCode,
 long millisecondsDelay)

从接口复制的说明: ICancelTokenSource

在一段时间后发送取消命令

指定者:

cancelAfter 在接口中 ICancelTokenSource

参数:

cancelCode - 取消码

millisecondsDelay - 延迟时间(毫秒) -- 单线程版的话，真实单位取决于约定。

cancelAfter

public void cancelAfter(int cancelCode,
 long delay,
 TimeUnit timeUnit)

在一段时间后发送取消命令 (将由默认的调度器调度)

指定者:

cancelAfter 在接口中 ICancelTokenSource

参数:

cancelCode - 取消码

delay - 延迟时间

timeUnit - 时间单位

cancelAfter

public void cancelAfter(int cancelCode,
 long delay,
 TimeUnit timeUnit,
 ScheduledExecutorService executor)

cancelCode

public int cancelCode()

从接口复制的说明: ICancelToken

取消码 1. 按bit位存储信息，包括是否请求中断，是否超时，紧急程度等 2. 低20位为取消原因；高12位为特殊信息 CancelCodes.MASK_REASON 3. 不为0表示已发起取消请求 4. 取消时至少赋值一个信息，reason通常应该赋值

指定者:

cancelCode 在接口中 ICancelToken

isCancelling

public boolean isCancelling()

从接口复制的说明: ICancelToken

是否已收到取消信号 任务的执行者将持有该令牌，在调度任务前会检测取消信号；如果任务已经开始，则由用户的任务自身检测取消和中断信号。

指定者:

isCancelling 在接口中 ICancelToken

reason

public int reason()

从接口复制的说明: ICancelToken

取消的原因 (1~10为底层使用，10以上为用户自定义)T

指定者:

reason 在接口中 ICancelToken

degree

public int degree()

从接口复制的说明: ICancelToken

取消的紧急程度

指定者:

degree 在接口中 ICancelToken

isInterruptible

public boolean isInterruptible()

从接口复制的说明: ICancelToken

取消指令中是否要求了中断线程

指定者:

isInterruptible 在接口中 ICancelToken

isWithoutRemove

public boolean isWithoutRemove()

从接口复制的说明: ICancelToken

取消指令中是否要求了无需删除

指定者:

isWithoutRemove 在接口中 ICancelToken

checkCancel

public void checkCancel()

从接口复制的说明: ICancelToken

检测取消信号 如果收到取消信号，则抛出CancellationException

指定者:

checkCancel 在接口中 ICancelToken

thenAccept

public IRegistration thenAccept(Consumer<? super ICancelToken> action,
 int options)

从接口复制的说明: ICancelToken

添加的action将在Context收到取消信号时执行 1.如果已收到取消请求，则给定的action会立即执行。 2.如果尚未收到取消请求，则给定action会在收到请求时执行。

指定者:

thenAccept 在接口中 ICancelToken

thenAccept

public IRegistration thenAccept(Consumer<? super ICancelToken> action)

指定者:

thenAccept 在接口中 ICancelToken

thenAcceptAsync

public IRegistration thenAcceptAsync(Executor executor,
 Consumer<? super ICancelToken> action)

指定者:

thenAcceptAsync 在接口中 ICancelToken

thenAcceptAsync

public IRegistration thenAcceptAsync(Executor executor,
 Consumer<? super ICancelToken> action,
 int options)

指定者:

thenAcceptAsync 在接口中 ICancelToken

thenAccept

public IRegistration thenAccept(BiConsumer<? super ICancelToken,Object> action,
 Object ctx,
 int options)

指定者:

thenAccept 在接口中 ICancelToken

thenAccept

public IRegistration thenAccept(BiConsumer<? super ICancelToken,Object> action,
 Object ctx)

指定者:

thenAccept 在接口中 ICancelToken

thenAcceptAsync

public IRegistration thenAcceptAsync(Executor executor,
 BiConsumer<? super ICancelToken,Object> action,
 Object ctx)

指定者:

thenAcceptAsync 在接口中 ICancelToken

thenAcceptAsync

public IRegistration thenAcceptAsync(Executor executor,
 BiConsumer<? super ICancelToken,Object> action,
 Object ctx,
 int options)

指定者:

thenAcceptAsync 在接口中 ICancelToken

thenRun

public IRegistration thenRun(Runnable action,
 int options)

指定者:

thenRun 在接口中 ICancelToken

thenRun

public IRegistration thenRun(Runnable action)

指定者:

thenRun 在接口中 ICancelToken

thenRunAsync

public IRegistration thenRunAsync(Executor executor,
 Runnable action)

指定者:

thenRunAsync 在接口中 ICancelToken

thenRunAsync

public IRegistration thenRunAsync(Executor executor,
 Runnable action,
 int options)

指定者:

thenRunAsync 在接口中 ICancelToken

thenRun

public IRegistration thenRun(Consumer<Object> action,
 Object ctx,
 int options)

指定者:

thenRun 在接口中 ICancelToken

thenRun

public IRegistration thenRun(Consumer<Object> action,
 Object ctx)

指定者:

thenRun 在接口中 ICancelToken

thenRunAsync

public IRegistration thenRunAsync(Executor executor,
 Consumer<Object> action,
 Object ctx)

指定者:

thenRunAsync 在接口中 ICancelToken

thenRunAsync

public IRegistration thenRunAsync(Executor executor,
 Consumer<Object> action,
 Object ctx,
 int options)

指定者:

thenRunAsync 在接口中 ICancelToken

thenNotify

public IRegistration thenNotify(CancelTokenListener action,
 int options)

从接口复制的说明: ICancelToken

添加一个特定类型的监听器 (用于特殊需求时避免额外的闭包 - task经常需要监听取消令牌)

指定者:

thenNotify 在接口中 ICancelToken

thenNotify

public IRegistration thenNotify(CancelTokenListener action)

指定者:

thenNotify 在接口中 ICancelToken

thenNotifyAsync

public IRegistration thenNotifyAsync(Executor executor,
 CancelTokenListener action)

指定者:

thenNotifyAsync 在接口中 ICancelToken

thenNotifyAsync

public IRegistration thenNotifyAsync(Executor executor,
 CancelTokenListener action,
 int options)

指定者:

thenNotifyAsync 在接口中 ICancelToken

thenTransferTo

public IRegistration thenTransferTo(ICancelTokenSource child)

指定者:

thenTransferTo 在接口中 ICancelToken

thenTransferTo

public IRegistration thenTransferTo(ICancelTokenSource child,
 int options)

从接口复制的说明: ICancelToken

该接口用于方便构建子上下文 1.子token会在当前token进入取消状态时被取消 2.该接口本质是一个快捷方法，但允许子类优化

注意：在Future体系下，child是上游任务；而在行为树这类体系下，child是下游任务。

指定者:

thenTransferTo 在接口中 ICancelToken

参数:

child - 接收结果的子token

options - 调度选项

thenTransferToAsync

public IRegistration thenTransferToAsync(Executor executor,
 ICancelTokenSource child)

指定者:

thenTransferToAsync 在接口中 ICancelToken

thenTransferToAsync

public IRegistration thenTransferToAsync(Executor executor,
 ICancelTokenSource child,
 int options)

指定者:

thenTransferToAsync 在接口中 ICancelToken