- data Ord a => Queue a
- data TaskHandle a
- data QueueOrder
- data Ord a => QueueConfigurationRecord a = QueueConfigurationRecord {
- queue_predicate :: STM ()
- priority_indexed_predicate :: a -> STM ()
- allowed_priority_inversion :: a -> a -> Bool
- allowed_ordering_inversion :: Int
- queue_order :: !QueueOrder
- fair_queue_configuration :: Ord a => QueueConfigurationRecord a
- fast_queue_configuration :: Ord a => QueueConfigurationRecord a
- newQueue :: Ord a => QueueConfigurationRecord a -> IO (Queue a)
- taskPriority :: Ord a => TaskHandle a -> STM (Maybe a)
- taskQueue :: TaskHandle a -> Queue a
- pendingTasks :: Ord a => Queue a -> STM [TaskHandle a]
- isTopOfQueue :: TaskHandle a -> STM Bool
- hasCompleted :: TaskHandle a -> STM Bool
- putTask :: Ord a => Queue a -> a -> STM () -> STM (TaskHandle a)
- pullTask :: Ord a => Queue a -> STM (TaskHandle a)
- pullFromTop :: Ord a => TaskHandle a -> STM (TaskHandle a)
- pullSpecificTasks :: Ord a => [TaskHandle a] -> IO ()
- dispatchTasks :: Ord a => [(Queue a, a, STM ())] -> IO [TaskHandle a]
- flushQueue :: Ord a => Queue a -> IO ()
- load :: Ord a => Queue a -> STM Int
- isEmpty :: Ord a => Queue a -> STM Bool
Documentation
A prioritized Queue
. Prioritization is least-first, i.e. larger values are nicer.
A Queue
is not associated with any working thread, therefore, it is the client's responsibility to make sure that every pushed
task is also pulled, or the Queue
will stall. There are several ways to accomplish this:
- Call
pullTask
at least once for every call toputTask
. - Use
dispatchTasks
to push every task. - Use
flushQueue
whenever theQueue
is not empty.
data TaskHandle a Source
(Ord a, Eq a) => Eq (TaskHandle a) | |
Ord a => Ord (TaskHandle a) | |
Ord a => Prioritized (TaskHandle a) |
data QueueOrder Source
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 entireQueue
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.
QueueConfigurationRecord | |
|
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
.
taskPriority :: Ord a => TaskHandle a -> STM (Maybe a)Source
Get the priority of this task, which only exists if the task is still enqueued.
taskQueue :: TaskHandle a -> Queue aSource
Get the Queue
associated with this task.
pendingTasks :: Ord a => Queue a -> STM [TaskHandle a]Source
isTopOfQueue :: TaskHandle a -> STM BoolSource
True iff this task is poised at the top of it's Queue
.
hasCompleted :: TaskHandle a -> STM BoolSource
putTask :: Ord a => Queue a -> a -> STM () -> STM (TaskHandle a)Source
Put a task with it's priority value onto this queue. Returns a handle to the task.
pullFromTop :: Ord a => TaskHandle a -> STM (TaskHandle a)Source
Pull this task from the top of a Queue
, if it is already there.
If this task is top-of-queue, but it's predicates fail, then pullFromTop
may instead pull a lower-priority TaskHandle
.
pullSpecificTasks :: Ord a => [TaskHandle a] -> IO ()Source
Don't return until the given TaskHandle
s have been pulled from their associated Queue
s.
This doesn't guarantee that the TaskHandle
will ever be pulled, even when the TaskHandle
and Queue
are both viable.
You must concurrently arrange for every other TaskHandle
associated with the same Queue
to be pulled, or the Queue
will stall.
pullSpecificTasks
can handle lists TaskHandle
s that are distributed among several Queue
s, as well as a TaskHandle
s that have
already completed or complete concurrently from another thread.
dispatchTasks :: Ord a => [(Queue a, a, STM ())] -> IO [TaskHandle a]Source
"Fire and forget" some tasks on a separate thread.