swim.concurrent (SwimOS)

Timer, task, and continuation passing style interfaces, with lightweight scheduler and execution stage implementations.

Timers

A TimerFunction represents a function to invoke at a scheduled time. Scheduling a timer yields a TimerRef, which can be used to check the status of the timer, to reschedule it, and to cancel it. A Timer represents a stateful TimerFunction, with lifecycle callbacks, and a TimerContext that enables self-management.

Tasks

A TaskFunction represents a function to invoke as a sequential process in a concurrent environment. Registering a task yields a TaskRef, which is used to cue the task for execution. A Task represents a stateful TaskFunction, with lifecycle callbacks, and a TaskContext that enables self-management. A Task is like a primitive actor that lacks a builtin mailbox.

Cont

A Cont represents the continuation of an asynchronous operation. Cont has factory functions to construct various Continuation combinators. Sync implements a synchronous Continuation that continues the current thread of execution after an asynchronous operation completes.

Calls

A Call provides a handle used to eventually complete an asynchronous operation by invoking a Continuation. Although a Continuation can be completed directly, by invoking bind(T), or Cont.trap(Throwable), completeing a Continuation through a Call abstracts over the execution context in which the Continuation runs. For example, a Call returned by Stage.call(Cont) invokes its bound Continuation in an asynchronous task, preventing unbounded stack growth from occurring when chaining large numbers of Continuations together.

Schedules

A Schedule arranges for the on-time execution of timers. Clock implements a Schedule algorithm that efficiently scales to large numbers of timers.

Stages

A Stage concurrently executes sequential tasks. Theater implements an execution Stage backed by a ForkJoinPool.

Interface Summary
Interface	Description
Call<T>	Handle used to eventually complete an asynchronous operation by invoking a `Cont`inuation.
Cont<T>	Continuation of an asynchronous operation.
MainStage	`Stage` that can be started and stopped.
Preemptive	Function interface that callers can optionally invoke concurrently.
PullContext<T>
PullRequest<T>
Schedule	Timetable for executing timers at their scheduled times.
ScheduleDef	Marker interface for a `Schedule` definition.
Stage	An execution context in which to schedule tasks, create continuation calls, and set timers.
StageDef	Marker interface for a `Stage` definition.
Stay<T>	Backpressure aware continuation.
StayContext	Source that can delay continuations.
Task	Stateful `TaskFunction` to invoke as a sequential process on a concurrent execution `Stage`, with lifecycle callbacks, and a `TaskContext` for self-management.
TaskContext	Internal context that binds a `Task` to an execution `Stage`.
TaskFunction	Function to invoke as a sequential process on a concurrent execution `Stage`.
TaskRef	External handle to a `TaskFunction` bound to an execution `Stage`.
Timer	Stateful `TimerFunction` to invoke at a scheduled time, with lifecycle callbacks, and a `TimerContext` for self-management.
TimerContext	Internal context that binds a `Timer` to a `Schedule`.
TimerFunction	Function to invoke at a scheduled time.
TimerRef	External handle to a `TimerFunction` bound to a `Schedule`.

Class Summary
Class	Description
AbstractTask	Skeletal implementation of a stateful `Task`.
AbstractTimer	Skeletal implementation of a stateful `Timer`.
Clock	Hashed wheel timer `Schedule`.
ClockDef
ConcurrentTrancheQueue<T>
PushRequest<T>
SideStage	`Stage` wrapper that prevents its underlying stage from being started and stopped.
StageClock	`Clock` that invokes timer functions on an execution `Stage`, rather than on the clock thread.
Sync<T>	A `Cont`inuation whose completion can be synchronously awaited.
Theater	`Stage` that executes timers, tasks, and continuations on a `ForkJoinPool`.
TheaterDef