priority-sync-0.2.1.1: Cooperative task prioritization.

PrioritySync.PrioritySync

Synopsis

Documentation

data TaskHandle p a Source

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 aSource

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)Source

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

class Prioritized p Source

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 ()Source

data Constrained u Source

Require that all RoomConstraints be satisfied when acquiring a Room.

Constructors

Constrained 

data Unconstrained u Source

Don't check any RoomConstraints when acquiring a Room.

Constructors

Unconstrained 

newtype MaxThreads Source

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

Constructors

MaxThreads Int 

data Room u Source

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)Source

Create a new Room with some arbitrary user data.

userData :: Room u -> uSource

Get the user data associated with a Room.

data ClaimMode Source

Constructors

Acquire 
Release 

Instances

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

The number of tasks waiting on this TaskPool.

class Occupancy o whereSource

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

Methods

inUse :: o -> IO (Set ThreadId)Source

isEmpty :: o -> IO BoolSource

Instances

Occupancy (Room u) 
Ord p => Occupancy (TaskPool p u) 

data Ord a => QueueConfigurationRecord a Source

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 aSource

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

fast_queue_configuration :: Ord a => QueueConfigurationRecord aSource

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 Source

Constructors

FIFO 
FILO 

data TaskPool p u Source

Instances

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

A prioritized ClaimContext for a task pool.

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

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

Consider using simpleTaskPool if you have no special needs.

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

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

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

Wait until a queue is finished.