ganeti
Safe HaskellSafe

Ganeti.Utils.AsyncWorker

Description

Provides a general functionality for workers that run on the background and perform some task when triggered.

Each task can process multiple triggers, if they're coming faster than the tasks are being processed.

Properties:

  • If a worked is triggered, it will perform its action eventually. (i.e. it won't miss a trigger).
  • If the worker is busy, the new action will start immediately when it finishes the current one.
  • If the worker is idle, it'll start the action immediately.
  • If the caller uses triggerAndWait, the call will return just after the earliest action following the trigger is finished.
  • If the caller uses triggerWithResult, it will recive an Async value that can be used to wait for the result (which will be available once the earliest action following the trigger finishes).
  • If the worker finishes an action and there are no pending triggers since the start of the last action, it becomes idle and waits for a new trigger.
Synopsis

The definition and construction of asynchronous workers

data TriggerState i a Source #

Constructors

Idle 
Pending i [MVar a] 

addTrigger :: Monoid i => i -> Maybe (MVar a) -> TriggerState i a -> TriggerState i a Source #

Adds a new trigger to the current state (therefore the result is always Pending), optionally adding a MVar that will receive the output.

data AsyncWorker i a Source #

Represent an asynchronous worker whose single action execution returns a value of type a.

Constructors

AsyncWorker ThreadId (IORef (TriggerState i a)) (MVar ()) 

mkAsyncWorker :: (Monoid i, MonadBaseControl IO m) => (i -> m a) -> m (AsyncWorker i a) Source #

Given an action, construct an AsyncWorker.

mkAsyncWorker_ :: MonadBaseControl IO m => m a -> m (AsyncWorker () a) Source #

Given an action, construct an AsyncWorker with no input.

Triggering workers and obtaining their results

newtype Async a Source #

An asynchronous result that will eventually yield a value.

Constructors

Async 

Fields

wait :: MonadBase IO m => Async a -> m a Source #

Waits for an asynchronous result to finish and yield a value.

waitMany :: (MonadBase IO m, Traversable t) => t (Async a) -> m (t a) Source #

Waits for all asynchronous results in a collection to finish and yield a value.

triggerInternal :: (MonadBase IO m, Monoid i) => i -> Maybe (MVar a) -> AsyncWorker i a -> m () Source #

trigger :: (MonadBase IO m, Monoid i) => i -> AsyncWorker i a -> m () Source #

Trigger a worker, letting it run its action asynchronously, but do not wait for the result.

trigger_ :: MonadBase IO m => AsyncWorker () a -> m () Source #

Trigger a worker with no input, letting it run its action asynchronously, but do not wait for the result.

triggerWithResult :: (MonadBase IO m, Monoid i) => i -> AsyncWorker i a -> m (Async a) Source #

Trigger a worker and wait until the action following this trigger finishes. The returned Async value can be used to wait for the result of the action.

triggerWithResult_ :: MonadBase IO m => AsyncWorker () a -> m (Async a) Source #

Trigger a worker and wait until the action following this trigger finishes.

See triggerWithResult.

triggerWithResultMany :: (Traversable t, MonadBase IO m, Monoid i) => i -> t (AsyncWorker i a) -> m (t (Async a)) Source #

Trigger a list of workers and wait until all the actions following these triggers finish. The returned collection of Async values can be used to wait for the results of the actions.

triggerWithResultMany_ :: (Traversable t, MonadBase IO m) => t (AsyncWorker () a) -> m (t (Async a)) Source #

Trigger a list of workers with no inputs and wait until all the actions following these triggers finish.

See triggerWithResultMany.

Helper functions for waiting for results just after triggering workers

triggerAndWaitMany :: (Traversable t, MonadBase IO m, Monoid i) => i -> t (AsyncWorker i a) -> m (t a) Source #

Trigger a list of workers and wait until all the actions following these triggers finish. Returns the results of the actions.

Note that there is a significant difference between triggerAndWaitMany and mapM triggerAndWait. The latter runs all the actions of the workers sequentially, while the former runs them in parallel.

triggerAndWaitMany_ :: (Traversable t, MonadBase IO m) => t (AsyncWorker () a) -> m (t a) Source #

triggerAndWait :: (MonadBase IO m, Monoid i) => i -> AsyncWorker i a -> m a Source #

Trigger a worker and wait until the action following this trigger finishes. Return the result of the action.

triggerAndWait_ :: MonadBase IO m => AsyncWorker () a -> m a Source #

Trigger a worker with no input and wait until the action following this trigger finishes. Return the result of the action.