Sebastian's Gopherspace (HTTP Gateway)

Introduction
------------------------------------------------------------
 
supervise is a Clojure library for managing a worker thread
through a synchronized lifecycle. A component wraps a worker
function and provides synchronous lifecycle operations
through start! and stop!. State transitions can be observed
through an optional callback.
 
Work in progress: supervise is under active development. Its
API, semantics, and implementation details may still change.
The library should not yet be considered a stable production
dependency.
 
 
Installation
------------------------------------------------------------
 
This library can be installed from Clojars [1].
 
 
Creating a component
------------------------------------------------------------
 
Create a component by passing a worker function and,
optionally, an options map to component:
 
  (require '[supervise.core :as supervise])
 
  (def service
    (supervise/component
      (fn [interrupt-token]
        (loop []
          ;; Perform the worker's task.
          (supervise/await! interrupt-token 1000)
          (recur)))
      {:restart-after-termination? true
       :restart-after-failure? true
       :on-transit println}))
 
When no options are needed, the options map can be omitted:
 
  (def service (supervise/component worker-fn))
 
The worker function, options map, and values assigned to
supported options are validated when the component is
created. Invalid arguments cause an ExceptionInfo containing
Clojure Spec explanation data.
 
The worker function receives an interrupt token. check!
checks whether the worker has been interrupted, while await!
waits for the specified number of milliseconds. Both
functions must be called from the worker thread associated
with the token. They throw InterruptedException after an
interrupt. When the interrupt was requested by stop!,
supervise handles it as the worker stopping normally. An
InterruptedException without an active stop request is
treated as a worker failure and retained as its cause.
 
 
start!
------------------------------------------------------------
 
  (supervise/start! service)
 
start! starts the worker and blocks until it has reached
:running. It returns nil on success.
 
The exact behavior depends on the component's current state:
 
  * In :stopped, a new worker generation is created and
    started.
  * In :starting, the call waits for the start already in
    progress. It does not create a second worker.
  * In :running, the call has no effect and immediately
    returns nil.
  * In :stopping, the call waits until the current worker
    has stopped and then evaluates again whether it may
    start a worker.
  * In :terminated, a new worker is started only when
    :restart-after-termination? is enabled. Otherwise,
    start! throws an ExceptionInfo containing the
    :terminated state.
  * In :failed, a new worker is started only when
    :restart-after-failure? is enabled. Otherwise, start!
    throws an ExceptionInfo containing the :failed state and
    the original failure as its cause.
 
If the underlying Java thread cannot be started, the
component transitions to :failed, and start! rethrows the
error.
 
Concurrent calls to start! create only one worker for the
same start attempt. The other calls wait for that worker to
start or observe that the component is already running.
 
The component's own worker must not call start! while the
component is stopping because it cannot wait synchronously
for its own thread to terminate. Such a call is rejected
with an IllegalStateException.
 
 
stop!
------------------------------------------------------------
 
  (supervise/stop! service)
 
stop! attempts to interrupt a running worker and blocks
until its thread has terminated. Once the thread terminates,
it returns nil even when the worker finishes in :failed; the
failure remains observable through :on-transit and when
automatic restart after failure is disabled, as the cause of
a subsequent rejected start!.
 
If interrupting the worker throws, stop! propagates the
exception. The component remains in :running, and no
:stopping notification is emitted, so a later stop! can try
again.
 
Its exact behavior also depends on the current state:
 
  * In :starting, the call first waits for the start to
    complete and then tries to stop the component again.
  * In :running, the call interrupts the worker while
    holding the lifecycle lock. If the interrupt succeeds,
    the component transitions to :stopping and the call
    waits for the worker thread to terminate.
  * In :stopping, the call waits for the stop already in
    progress to complete.
  * In :stopped, :terminated, or :failed, the call has no
    effect and immediately returns nil.
 
stop! must not be called synchronously from the component's
own worker thread. Such a call could wait for the same
thread to terminate and is therefore rejected with an
IllegalStateException. A worker should instead return from
its function when it needs to terminate itself.
 
Interruption is cooperative: the worker must react to the
interrupt, for example by calling check! or await!, or by
using another interruptible operation. If it ignores the
interrupt, stop! continues waiting until the worker actually
terminates.
 
 
States
------------------------------------------------------------
 
A component can be in one of the following states:
 
:stopped
  The initial state or the result of a successful stop!. No
  worker is running.
 
:starting
  A new worker generation has been created, but its thread
  has not yet reported :running.
 
:running
  The worker has started and is executing its function.
 
:stopping
  The worker has been asked to stop, but its thread has not
  yet terminated.
 
:terminated
  The worker function returned on its own without an error.
 
:failed
  The worker function, an unexpected interruption, or the
  attempt to start its thread failed. The error is retained
  as the cause.
 
 
Lifecycle diagram
 
 
Restart options
------------------------------------------------------------
 
:restart-after-termination?
---------------------------
 
When this option is true, start! may start a new worker
generation for a component in :terminated. Without the
option, a component whose worker terminated normally cannot
be started again.
 
  {:restart-after-termination? true}
 
 
:restart-after-failure?
-----------------------
 
When this option is true, start! may start a new worker
generation for a component in :failed. The previously stored
failure is cleared for the new start. Without the option,
start! exposes the previous failure as its cause.
 
  {:restart-after-failure? true}
 
Both options are disabled by default and accept boolean
values. They affect only start! in their respective terminal
states. A worker that was explicitly stopped can always be
started again from :stopped.
 
 
Lifecycle notifications and generations
------------------------------------------------------------
 
Use :on-transit to register a function that receives a map
for every state transition:
 
  {:on-transit
   (fn [{:keys [generation from to cause]}]
     (println "Generation" generation ":" from "->" to)
     (when cause
       (println "Cause:" cause)))}
 
Each notification contains the following keys:
 
  * :generation is the worker generation number. It starts
    at 1 for the first start and increases whenever a new
    worker is actually created.
  * :from is the previously reported state.
  * :to is the new state.
  * :cause is the original throwable and is present only
    when :to is :failed.
 
Callbacks run asynchronously, but in the same order as the
state transitions. A slow callback therefore does not block
start!, stop!, or the worker. Callback errors are caught so
that subsequent notifications can still be delivered.
 
Listeners can also be added and removed while the component
is running:
 
  (def listener #(println "transition:" %))
 
  (supervise/add-listener! service listener)
  (supervise/remove-listener! service listener)
 
Listeners run asynchronously. Registering the same listener
more than once has no effect, and their invocation order is
unspecified. Removing an unknown listener has no effect.
Because delivery is asynchronous, an event already queued
when a listener is removed may still be delivered to it.
 
 
References
------------------------------------------------------------
[1]: Clojars
 
 
Links
------------------------------------------------------------
main.zip
GitHub