runtime-core/io.matthewnelson.kmp.tor.runtime.core/EnqueuedJob

EnqueuedJob

abstract class EnqueuedJob(val name: String, onFailure: OnFailure, handler: UncaughtException.Handler)(source)

Base abstraction for single-use model that tracks the state of a queue-able job. Once completed, either successfully or by cancellation/error, the EnqueuedJob is dead and should be discarded.

Heavily inspired by kotlinx.coroutines.Job

Constructors

EnqueuedJob

protected constructor(name: String, onFailure: OnFailure, handler: UncaughtException.Handler)

Types

Companion

object Companion

ExecutionPolicy

class ExecutionPolicy

Dynamic configuration for implementors of EnqueuedJob in order to modify how it wants to handle interactions while in a state of Executing.

State

enum State : Enum<EnqueuedJob.State>

Properties

executionPolicy

open val executionPolicy: EnqueuedJob.ExecutionPolicy

The ExecutionPolicy of this job.

isActive

@get:JvmName(name = "isActive")

val isActive: Boolean

Checks if the job is in a completion state or not.

isCancelled

@get:JvmName(name = "isCancelled")

val isCancelled: Boolean

If state is State.Cancelled

isCompleting

@get:JvmName(name = "isCompleting")

val isCompleting: Boolean

An intermediate "state" indicating that completion, either by success or error/cancellation, is underway.

isError

@get:JvmName(name = "isError")

val isError: Boolean

If state is State.Error

isSuccess

@get:JvmName(name = "isSuccess")

val isSuccess: Boolean

If state is State.Success

name

@JvmField

val name: String

The name for this job. Will be utilized with error handling for contextual purposes.

state

@get:JvmName(name = "state")

val state: EnqueuedJob.State

The current State of the job.

Functions

cancel

fun cancel(cause: CancellationException?): Boolean

Cancel the job.

cancellationAttempt

protected fun cancellationAttempt(): CancellationException?

If cancel was called while the EnqueuedJob is in a non-cancellable state (i.e. Executing), and the implementing class has declared a ExecutionPolicy allowing for it, this will be set in order to signal for cancellation.

invokeOnCompletion

fun invokeOnCompletion(handle: ItBlock<CancellationException?>): Disposable

Register a handle to be invoked when this EnqueuedJob completes, either successfully or by cancellation/error. If handle is already registered, Disposable.noOp is returned.

onCancellation

protected open fun onCancellation(cause: CancellationException?)

Notifies the implementation that the EnqueuedJob has been cancelled in order to perform cleanup, if necessary.

onCompletion

protected fun <T> onCompletion(response: T, withLock: () -> OnSuccess<T>??): Boolean

Sets the job state to State.Success and invokes OnSuccess returned by withLock with provided response. Does nothing if the job is completed or completing.

onError

protected fun onError(cause: Throwable, withLock: ItBlock<Throwable>?): Boolean

Sets the job state to State.Error and invokes OnFailure with provided cause. Does nothing if the job is completed or completing.

onExecuting

protected fun onExecuting()

Moves the state from Enqueued to Executing, indicating that the caller has "taken ownership" of the EnqueuedJob.

EnqueuedJob

See also

Constructors

Types

Properties

Functions