Only one thread is running Async code at a time. This is enforced by a single lock in
Async's scheduler data structure. There are any number of threads running code
without holding the lock that get data from the outside world and want to affect the
Async world. They do this by calling
Thread_safe.run_in_async*, which acquires the
lock, does a computation (e.g. fills an ivar), and then runs a "cycle" of Async
t () returns the Async scheduler. If the scheduler hasn't been created yet, this
will create it and acquire the Async lock.
go ?raise_unhandled_exn () passes control to Async, at which point Async starts
running handlers, one by one without interruption, until there are no more handlers to
run. When Async is out of handlers it blocks until the outside world schedules more
of them. Because of this, Async programs do not exit until
shutdown is called.
go () calls
handle_signal Sys.sigpipe, which causes the SIGPIPE signal to be
ignored. Low-level syscalls (e.g. write) still raise EPIPE.
If any Async job raises an unhandled exception that is not handled by any monitor,
Async execution ceases. Then, by default, Async pretty prints the exception, and
exits with status 1. If you don't want this, pass
will cause the unhandled exception to be raised to the caller of
go_main is like
go, except that one supplies a
main function that will be run to
initialize the Async computation, and that
go_main will fail if any Async has been
used prior to
go_main being called. Moreover it allows to configure more static
options of the scheduler.
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
never become determined, but the exception will end up in the specified monitor.
within is like
within', but doesn't require thunk to return a deferred.
within_v is like
within, but allows a value to be returned by
with_local key value ~f, when run in the current execution context,
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
with_local returns, the execution context is
find_local key returns the value associated to
key in the current execution
Just like schedule', but doesn't require thunk to return a deferred.
preserve_execution_context t f saves the current execution context and returns a
g such that
g a runs
f a in the saved execution context.
g a becomes
f a becomes determined.
cycle_start () returns the result of
Time.now () called at the beginning of
report_long_cycle_times ?cutoff () sets up something that will print a warning to
stderr whenever there is an Async cycle that is too long, as specified by
whose default is 1s.
cycle_count () returns the total number of Async cycles that have happened.
alarm_precision of the timing-wheel used to implement Async's
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.
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
set_max_inter_cycle_timeout span sets the maximum amount of time the scheduler will
remain blocked (on epoll or select) between cycles.
set_check_invariants do_check sets whether Async should check invariants of its
internal data structures.
set_check_invariants true can substantially slow down
set_detect_invalid_access_from_thread do_check sets whether Async routines should
check if they are being accessed from some thread other than the thread currently
holding the Async lock, which is not allowed and can lead to very confusing
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.
fold_fields ~init folder folds
folder over each field in the scheduler. The
fields themselves are not exposed --
folder must be a polymorphic function that
can work on any field. So, it's only useful for generic operations, e.g. getting
the size of each field.
If a process that has already created, but not started, the Async scheduler would like
to fork, and would like the child to have a clean Async, i.e. not inherit any of the
Async work that was done in the parent, it can call
reset_in_forked_process at the
start of execution in the child process. After that, the child can do Async stuff and
then start the Async scheduler.
Async supports "busy polling", which runs a thread that busy loops running user-supplied polling functions. The busy-loop thread is distinct from Async's scheduler thread.
Busy polling is useful for a situation like a shared-memory ringbuffer being used for IPC. One can poll the ringbuffer with a busy poller, and then when data is detected, fill some ivar that causes Async code to handle the data.
add_busy_poller poll adds
poll to the busy loop.
poll will be called
continuously, once per iteration of the busy loop, until it returns
at which point the result of
add_busy_poller will become determined.
hold the Async lock while running, so it is fine to do ordinary Async operations,
e.g. fill an ivar. The busy loop will run an ordinary Async cycle if any of the
pollers add jobs.
poll will run in monitor in effect when
add_busy_poller was called; exceptions
poll will be sent asynchronously to that monitor. If
poll raises, it
will still be run on subsequent iterations of the busy loop.
handle_thread_pool_stuck f causes
f to run whenever Async detects its thread pool
is stuck (i.e. hasn't completed a job for over a second and has work waiting to
start). Async checks every second. By default, if thread pool has been stuck for
less than 60s, Async will
eprintf a message. If more than 60s, Async will send an
exception to the main monitor, which will abort the program unless there is a custom
handler for the main monitor.
handle_thread_pool_stuck replaces whatever behavior was previously there.
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.
yield_every ~n returns a function that will act as
n calls and as
Deferred.unit 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.
time_spent_waiting_for_io () returns the amount of time that the Async scheduler has
spent in calls to
select) since the start of the program.
set_min_inter_cycle_timeout sets the minimum timeout that the scheduler will pass to
the OS when it checks for I/O between cycles. The minimum is zero by default.
Setting it to a nonzero value is used to increase thread fairness between the
scheduler and other threads. A plausible setting is 1us. This can also be set via
ASYNC_CONFIG environment variable.