Main type for scheduling work. See withScheduler or withScheduler_ for ways to construct and use this data type.

Since: 1.0.0

This is a wrapper around Scheduler, but it also keeps a separate state for each individual worker. See withSchedulerWS or withSchedulerWS_ for ways to construct and use this data type.

Since: 1.4.0

Computed outcome of scheduled jobs.

Since: 1.4.2

Initialize a scheduler and submit jobs that will be computed sequentially or in parallelel, which is determined by the Computation strategy.

Here are some cool properties about the withScheduler:

• This function will block until all of the submitted jobs have finished or at least one of them resulted in an exception, which will be re-thrown at the callsite.
• It is totally fine for nested jobs to submit more jobs for the same or other scheduler
• It is ok to initialize multiple schedulers at the same time, although that will likely result in suboptimal performance, unless workers are pinned to different capabilities.
• Warning It is pretty dangerous to schedule jobs that do blocking IO, since it can easily lead to deadlock, if you are not careful. Consider this example. First execution works fine, since there are two scheduled workers, and one can unblock the other, but the second scenario immediately results in a deadlock.

>>> withScheduler (ParOn [1,2]) $ \s -> newEmptyMVar >>= (\ mv -> scheduleWork s (readMVar mv) >> scheduleWork s (putMVar mv ()))
[(),()]
>>> import System.Timeout
>>> timeout 1000000 $ withScheduler (ParOn [1]) $ \s -> newEmptyMVar >>= (\ mv -> scheduleWork s (readMVar mv) >> scheduleWork s (putMVar mv ()))
Nothing

Important: In order to get work done truly in parallel, program needs to be compiled with -threaded GHC flag and executed with +RTS -N -RTS to use all available cores.

Since: 1.0.0

Same as withScheduler, but discards results of submitted jobs.

Since: 1.0.0

Same as withScheduler, except instead of a list it produces Results, which allows for distinguishing between the ways computation was terminated.

Since: 1.4.2

Run a scheduler with stateful workers. Throws MutexException if an attempt is made to concurrently use the same WorkerStates with another SchedulerWS.

Examples

>>> import Control.Monad as M ((>=>), replicateM)
>>> import Control.Concurrent (yield, threadDelay)
>>> import Data.List (sort)
>>> -- ^ Above imports are used to make sure output is deterministic, which is needed for doctest
>>> import System.Random.MWC as MWC
>>> import Data.Vector.Unboxed as V (singleton)
>>> states <- initWorkerStates (ParN 4) (MWC.initialize . V.singleton . fromIntegral . getWorkerId)
>>> let scheduleGen scheduler = scheduleWorkState scheduler (MWC.uniform >=> \r -> yield >> threadDelay 200000 >> pure r)
>>> sort <$> withSchedulerWS states (M.replicateM 4 . scheduleGen) :: IO [Double]
[0.21734983682025255,0.5000843862105709,0.5759825622603018,0.8587171114177893]
>>> sort <$> withSchedulerWS states (M.replicateM 4 . scheduleGen) :: IO [Double]
[2.3598617298033475e-2,9.949679290089553e-2,0.38223134248645885,0.7408640677124702]

Since: 1.4.0

Run a scheduler with stateful workers, while discarding computation results.

Since: 1.4.0

Same as withSchedulerWS, except instead of a list it produces Results, which allows for distinguishing between the ways computation was terminated.

Since: 1.4.2

Get the underlying Scheduler, which cannot access WorkerStates.

Since: 1.4.0

The most basic scheduler that simply runs the task instead of scheduling it. Early termination requests are bluntly ignored.

Since: 1.1.0

This trivial scheduler will behave in the same way as withScheduler with Seq computation strategy, except it is restricted to PrimMonad, instead of MonadUnliftIO.

Since: 1.4.2

This trivial scheduler will behave in a similar way as withSchedulerR with Seq computation strategy, except it is restricted to PrimMonad, instead of MonadUnliftIO and the work isn't scheduled, but rather computed immediately.

Since: 1.4.2

Schedule an action to be picked up and computed by a worker from a pool of jobs. Similar to scheduleWorkId, except the job doesn't get the worker id.

Since: 1.0.0

Same as scheduleWork, but only for a Scheduler that doesn't keep the results.

Since: 1.1.0

Schedule an action to be picked up and computed by a worker from a pool of jobs. Argument supplied to the job will be the id of the worker doing the job.

Since: 1.2.0

Same as scheduleWorkId, but only for a Scheduler that doesn't keep the results.

Since: 1.2.0

Schedule a job that will get a worker state passed as an argument

Since: 1.4.0

Same as scheduleWorkState, but dont' keep the result of computation.

Since: 1.4.0

Schedule the same action to run n times concurrently. This differs from replicateConcurrently by allowing the caller to use the Scheduler freely, or to allow early termination via terminate across all (identical) threads. To be called within a withScheduler block.

Since: 1.4.1

As soon as possible try to terminate any computation that is being performed by all workers managed by this scheduler and collect whatever results have been computed, with supplied element guaranteed to being the last one. In case when Results is the return type this function will cause the scheduler to produce FinishedEarly

Important - With Seq strategy this will not stop other scheduled tasks from being computed, although it will make sure their results are discarded.

Since: 1.1.0

Similar to terminate, but for a Scheduler that does not keep any results of computation.

Important - In case of Seq computation strategy this function has no affect.

Since: 1.1.0

Same as terminate, but returning a single element list containing the supplied argument. This can be very useful for parallel search algorithms. In case when Results is the return type this function will cause the scheduler to produce FinishedEarlyWith

Important - Same as with terminate, when Seq strategy is used, this will not prevent computation from continuing, but the scheduler will return only the result supplied to this function.

Since: 1.1.0

A unique id for the worker in the Scheduler context. It will always be a number from 0 up to, but not including, the number of workers a scheduler has, which in turn can always be determined with numWorkers function.

Since: 1.4.0

Each worker is capable of keeping it's own state, that can be share for different schedulers, but not at the same time. In other words using the same WorkerStates on withSchedulerS concurrently will result in an error. Can be initialized with initWorkerStates

Since: 1.4.0

Get the number of workers. Will mainly depend on the computation strategy and/or number of capabilities you have. Related function is getCompWorkers.

Since: 1.0.0

Get the computation strategy the states where initialized with.

Since: 1.4.0

Initialize a separate state for each worker.

Since: 1.4.0

Computation strategy to use when scheduling work.

Figure out how many workers will this computation strategy create.

Note - If at any point during program execution global number of capabilities gets changed with setNumCapabilities, it will have no affect on this function, unless it hasn't yet been called with Par or Par' arguments.

Since: 1.1.0

Replicate an action n times and schedule them acccording to the supplied computation strategy.

Since: 1.1.0

Just like replicateConcurrently, but discards the results of computation.

Since: 1.1.0

Map an action over each element of the Traversable t acccording to the supplied computation strategy.

Since: 1.0.0

Just like traverseConcurrently, but restricted to Foldable and discards the results of computation.

Since: 1.0.0

This is generally a faster way to traverse while ignoring the result rather than using mapM_.

Since: 1.0.0

Exception that gets thrown whenever concurrent access is attempted to the WorkerStates

Since: 1.4.0