PrioritySync.PrioritySync

Documentation

data TaskHandle p a

Instances

Prioritized (TaskHandle p a)

Change the priority of a task. This will not work if the task has already started.

claim :: (RoomGroup c, ClaimContext c) => ClaimMode -> c -> IO a -> IO a

Temporarily Acquire, and then release, or Release, and then acquire, some Rooms for the duration of a critical section. A simple example where a room might be used to prevent interleaving of stdout:

 room <- newRoom (MaxThreads 1)
 forkIO $ claim Acquire (Default,room) $ putStrLn "Hello World!"
 forkIO $ claim Acquire (Default,room) $ putStrLn "Foo!  Bar!"

dispatch :: (RoomGroup c, ClaimContext c, Prioritized (ClaimHandle c)) => c -> IO a -> IO (TaskHandle (Priority (ClaimHandle c)) a)

Perform a task on another thread. This task can be reprioritized and canceled.

getResult :: TaskHandle p a -> IO a

tryGetResult :: TaskHandle p a -> IO (Maybe a)

class Prioritized p

Reprioritize a task. This has no effect on a target that has already left the queue.

Instances

Prioritized p => Prioritized (Maybe p)

Ord a => Prioritized (TaskHandle a)

Prioritized (TaskHandle p a)

Change the priority of a task. This will not work if the task has already started.

reprioritize :: TaskHandle p a -> (p -> p) -> IO ()

data Constrained u

Require that all RoomConstraints be satisfied when acquiring a Room.

Constructors

Constrained

Instances

RoomConstraint u => ClaimContext (Constrained u)

RoomGroup (Constrained u)

data Unconstrained u

Don't check any RoomConstraints when acquiring a Room.

Constructors

Unconstrained

Instances

ClaimContext (Unconstrained u)

RoomGroup (Unconstrained u)

newtype MaxThreads

A maximum limit on the number of threads allowed to claim a room.

Constructors

MaxThreads Int

Instances

RoomConstraint MaxThreads

data Room u

A resource pool, parameterized against arbitrary user data.

Instances

Eq (Room u)

Ord (Room u)

RoomGroup (Room u)

Occupancy (Room u)

newRoom :: u -> IO (Room u)

Create a new Room with some arbitrary user data.

userData :: Room u -> u

Get the user data associated with a Room.

data ClaimMode

Constructors

Acquire

Release

Instances

Eq ClaimMode

load :: Ord p => TaskPool p u -> IO Int

The number of tasks waiting on this TaskPool.

class Occupancy o where

A convenience class to observe the currently running occupants of a Room or TaskPool.

Methods

inUse :: o -> IO (Set ThreadId)

isEmpty :: o -> IO Bool

Instances

Occupancy (Room u)

Ord p => Occupancy (TaskPool p u)

data Ord a => QueueConfigurationRecord a

Configuration options for a Queue. A Queue blocks on a number of predicates when dispatching a job. Generally, fair_queue_configuration should work well.

• A single STM predicate for the entire Queue. This blocks the entire Queue until the predicate is satisfied.
• A STM predicate parameterized by priority. This blocks a single priority level, and the Queue will skip all tasks at that priority.
• Each task is itself an STM transaction, and can block itself.
• Pure constraints on priority and ordering inversion.

If a task is blocked for any reason, the task is skipped and the next task attempted, in priority order.

Constructors

QueueConfigurationRecord

Fields

queue_predicate :: STM ()

A predicate that must hold before any task may be pulled from a Queue.

priority_indexed_predicate :: a -> STM ()

A predicate that must hold before any priority level may be pulled from a Queue.

allowed_priority_inversion :: a -> a -> Bool

Constrains the greatest allowed difference between the priority of the top-of-queue task and the priority of a task to be pulled.

allowed_ordering_inversion :: Int

The greatest allowed difference between the ideal prioritized FILO/FIFO ordering of tasks and the actual ordering of tasks. Setting this too high can introduce a lot of overhead in the presence of a lot of short-running tasks. Setting this to zero turns off the predicate failover feature, i.e. only the top of queue task will ever be pulled.

queue_order :: !QueueOrder

Should the Queue run in FILO or FIFO order. Ordering takes place after prioritization, and won't have much effect if priorities are very fine-grained.

fair_queue_configuration :: Ord a => QueueConfigurationRecord a

A queue tuned for high throughput and fairness when processing moderate to long running tasks.

fast_queue_configuration :: Ord a => QueueConfigurationRecord a

A queue tuned for high responsiveness and low priority inversion, but may have poorer long-term throughput and potential to starve some tasks compared to fair_queue_configuration.

data QueueOrder

Constructors

FIFO

FILO

data TaskPool p u

Instances

RoomGroup (TaskPool p u)

Ord p => Occupancy (TaskPool p u)

schedule :: TaskPool p u -> p -> Schedule p (Constrained (TaskPoolConstraint u), Room (TaskPoolConstraint u))

A prioritized ClaimContext for a task pool.

newTaskPool :: Ord p => QueueConfigurationRecord p -> Int -> u -> IO (TaskPool p u)

Create a new TaskPool. TaskPools begin stopped, use startQueue to start.

• A QueueConfigurationRecord for the backing Queue. A typical value is fair_queue_configuration.
• The allowed number of threads that can access the TaskPool simultaneously.
• The user data for the backing Room. This can be ().

Consider using simpleTaskPool if you have no special needs.

simpleTaskPool :: Ord p => IO (TaskPool p ())

Just create a new TaskPool. The task pool is constrained by the number of capabilities indicated by numCapabilities.

startQueue :: TaskPool p a -> IO ()

stopQueue :: TaskPool p a -> IO ()

waitUntilFinished :: Ord p => TaskPool p u -> IO ()

Wait until a queue is finished.