package async_kernel

  1. Overview
  2. Docs
package async_kernel
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Async_kernel.Async_kernel_schedulerSource

The Async scheduler is responsible for running Async jobs. It maintains the queue of jobs that need to run. A "cycle" consists of running some (possibly all) jobs in the queue, along with some other bookkeeping, like advancing Async's clock to the current time.

type 'a with_options := ?monitor:Monitor.t -> ?priority:Priority.t -> 'a
Sourceval current_execution_context : unit -> Execution_context.t
Sourceval within_context : Execution_context.t -> (unit -> 'a) -> ('a, unit) Core.Result.t

within_context context f runs f () right now with the specified execution context. If f raises, then the exception is sent to the monitor of context, and Error () is returned.

Sourceval within' : ((unit -> 'a Deferred.t) -> 'a Deferred.t) with_options

within' f ~monitor ~priority runs f () right now, with the specified block group, monitor, and priority set as specified. They will be reset to their original values when f returns. If f raises, then the result of within' will never become determined, but the exception will end up in the specified monitor.

Sourceval within : ((unit -> unit) -> unit) with_options

within is like within', but doesn't require the thunk to return a deferred.

Sourceval within_v : ((unit -> 'a) -> 'a option) with_options

within_v is like within, but allows a value to be returned by f.

Sourceval with_local : 'a Core.Univ_map.Key.t -> 'a option -> f:(unit -> 'b) -> 'b

with_local key value ~f, when run in the current execution context, e, runs f right now in a new execution context, e', that is identical to e except that find_local key = value. As usual, e' will be in effect in asynchronous computations started by f. When with_local returns, the execution context is restored to e.

Sourceval find_local : 'a Core.Univ_map.Key.t -> 'a option

find_local key returns the value associated to key in the current execution context.

Sourceval schedule' : ((unit -> 'a Deferred.t) -> 'a Deferred.t) with_options

Just like within', but instead of running the thunk right now, adds it to the Async queue to be run with other Async jobs.

Sourceval schedule : ((unit -> unit) -> unit) with_options

Just like schedule', but doesn't require the thunk to return a deferred.

Sourceval enqueue_job : Execution_context.t -> ('a -> unit) -> 'a -> unit

eneque_job execution_context.t f a enqueues into the scheduler's job queue a job that will run f a in execution_context.

Sourceval thread_safe_enqueue_job : Execution_context.t -> ('a -> unit) -> 'a -> unit

thread_safe_enqueue_job is like enqueue_job, except it is for use from a thread that doesn't hold the Async lock.

Sourceval preserve_execution_context : ('a -> unit) -> ('a -> unit) Core.Staged.t

preserve_execution_context t f saves the current execution context and returns a function g such that g a runs f a in the saved execution context. g a becomes determined when f a becomes determined.

Sourceval preserve_execution_context' : ('a -> 'b Deferred.t) -> ('a -> 'b Deferred.t) Core.Staged.t
Sourceval cycle_start : unit -> Core.Time_float.t

cycle_start () returns the result of Time.now () called at the beginning of cycle.

Sourceval cycle_start_ns : unit -> Core.Time_ns.t

cycle_times () returns a stream that is extended with an element at the start of each Async cycle, with the amount of time that the previous cycle took, as determined by calls to Time.now at the beginning and end of the cycle.

last_cycle_time returns the time spent in the most recently completed cycle.

long_cycles ~at_least returns a stream of cycles whose duration is at least at_least. long_cycles is more efficient than cycle_times because it only allocates a stream entry when there is a long cycle, rather than on every cycle.

Sourceval cycle_count : unit -> int

cycle_count () returns the total number of Async cycles that have happened.

total_cycle_time () returns the total (wall) time spent executing jobs in Async cycles.

Sourceval event_precision : unit -> Core.Time_float.Span.t

The alarm_precision of the timing-wheel used to implement Async's Clock.

Sourceval force_current_cycle_to_end : unit -> unit

force_current_cycle_to_end () causes no more normal priority jobs to run in the current cycle, and for the end-of-cycle jobs (i.e., writes) to run, and then for the cycle to end.

Sourceval set_max_num_jobs_per_priority_per_cycle : int -> unit

set_max_num_jobs_per_priority_per_cycle int sets the maximum number of jobs that will be done at each priority within each Async cycle. The default is 500. max_num_jobs_per_priority_per_cycle retrieves the current value.

Sourceval max_num_jobs_per_priority_per_cycle : unit -> int
Sourceval set_record_backtraces : bool -> unit

set_record_backtraces do_record sets whether Async should keep in the execution context the history of stack backtraces (obtained via Backtrace.get) that led to the current job. If an Async job has an unhandled exception, this backtrace history will be recorded in the exception. In particular the history will appear in an unhandled exception that reaches the main monitor. This can have a substantial performance impact, both in running time and space usage.

Sourceval recording_backtraces : unit -> bool
Sourceval yield : unit -> unit Deferred.t

yield () returns a deferred that becomes determined after the current cycle completes. This can be useful to improve fairness by yielding within a computation to give other jobs a chance to run.

Sourceval yield_until_no_jobs_remain : ?may_return_immediately:bool -> unit -> unit Deferred.t

yield_until_no_jobs_remain () returns a deferred that becomes determined the next time Async's job queue is empty. This is useful in tests when one needs to wait for the completion of all the jobs based on what's in the queue, when those jobs might create other jobs -- without depending on I/O or the passage of wall-clock time.

may_return_immediately determines how yield_until_no_jobs_remain behaves if the job queue is currently empty. If may_return_immediately = true, then yield_until_no_jobs_remain will return (). If may_return_immediately = false, then yield_until_no_jobs_remain's result will become determined after the next Async cycle. We hope to someday change the default may_return_immediately from false to true.

Sourceval yield_every : n:int -> (unit -> unit Deferred.t) Core.Staged.t

yield_every ~n returns a function that will act as yield every n calls and as return () the rest of the time. This is useful for improving fairness in circumstances where you don't have good control of the batch size, but can insert a deferred into every iteration.

yield_every raises if n <= 0.

Sourceval num_jobs_run : unit -> int

num_jobs_run () returns the number of jobs that have been run since starting. The returned value includes the currently running job.

Sourceval num_pending_jobs : unit -> int

num_pending_jobs returns the number of jobs that are queued to run by the scheduler.

Sourcemodule Expert : sig ... end
Sourcemodule Private : sig ... end

Internal to Async -- see Async_unix.Scheduler for the public API.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct