package async_kernel

We use a phantom type to distinguish between throttles, which have max_concurrent_jobs >= 1, and sequencers, which have max_concurrent_jobs = 1. All operations are available on both. We make the distinction because it is sometimes useful to know from the type of a throttle that it is a sequencer and that at most one job can be running at a time.

create ~continue_on_error ~max_concurrent_jobs returns a throttle that will run up to max_concurrent_jobs concurrently. If some job raises an exception, then the throttle will be killed, unless continue_on_error is true.

create_with ~continue_on_error job_resources returns a throttle that will run up to List.length job_resources concurrently, and will ensure that all running jobs are supplied distinct elements of job_resources.

enqueue t job schedules job to be run as soon as possible. Jobs are guaranteed to be started in the order they are enqueued and to not be started during the call to enqueue. If t is dead, then job will be immediately aborted (for enqueue, this will send an exception to the monitor in effect).

enqueue_exclusive schedules a job that occupies all slots of the throttle, so it won't run concurrently with any other job. The job counts as being enqueued normally, so it runs after the jobs enqueued previously and before the jobs enqueued later. enqueue_exclusive takes O(max_concurrent_jobs) time, so you should not use it when max_concurrent_jobs = Int.max_value.

monad_sequence_how ~how ~f returns a function that behaves like f, except that it uses a throttle to limit the number of concurrent invocations that can be running simultaneously. The throttle has continue_on_error = false.

prior_jobs_done t becomes determined when all of the jobs that were previously enqueued in t have completed.

max_concurrent_jobs t returns the maximum number of jobs that t will run concurrently.

num_jobs_running t returns the number of jobs that t is currently running. It is guaranteed that if num_jobs_running t < max_concurrent_jobs t then num_jobs_waiting_to_start t = 0. That is, the throttle always uses its maximum concurrency if possible.

num_jobs_waiting_to_start t returns the number of jobs that have been enqueued but have not yet started.

capacity_available t becomes determined the next time that t has fewer than max_concurrent_jobs t running, and hence an enqueued job would start immediately.

kill t kills t, which aborts all enqueued jobs that haven't started and all jobs enqueued in the future. kill also initiates the at_kill clean functions.

If t has already been killed, then calling kill t has no effect.

is_dead t returns true if t was killed, either by kill or by an unhandled exception in a job.

at_kill t clean runs clean on each resource when t is killed, either by kill or by an unhandled exception. clean is called on each resource as it becomes available, i.e., immediately if the resource isn't currently in use, otherwise when the job currently using the resource finishes. If a call to clean fails, the exception is raised to the monitor in effect when at_kill was called.

cleaned t becomes determined after t is killed, all its running jobs have completed, and all at_kill clean functions have completed.

A sequencer is a throttle that is specialized to only allow one job at a time and to, by default, not continue on error.