<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Read_write.html">
<link rel="next" href="Select_file_descr_watcher.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Async_print" rel="Chapter" href="Async_print.html">
<link title="Async_sys" rel="Chapter" href="Async_sys.html">
<link title="Epoll_file_descr_watcher" rel="Chapter" href="Epoll_file_descr_watcher.html">
<link title="Fd" rel="Chapter" href="Fd.html">
<link title="Fd_by_descr" rel="Chapter" href="Fd_by_descr.html">
<link title="File_descr_watcher_intf" rel="Chapter" href="File_descr_watcher_intf.html">
<link title="Import" rel="Chapter" href="Import.html">
<link title="Interruptor" rel="Chapter" href="Interruptor.html">
<link title="In_thread" rel="Chapter" href="In_thread.html">
<link title="Io_stats" rel="Chapter" href="Io_stats.html">
<link title="Process" rel="Chapter" href="Process.html">
<link title="Raw_fd" rel="Chapter" href="Raw_fd.html">
<link title="Raw_scheduler" rel="Chapter" href="Raw_scheduler.html">
<link title="Raw_signal_manager" rel="Chapter" href="Raw_signal_manager.html">
<link title="Reader" rel="Chapter" href="Reader.html">
<link title="Read_write" rel="Chapter" href="Read_write.html">
<link title="Scheduler" rel="Chapter" href="Scheduler.html">
<link title="Select_file_descr_watcher" rel="Chapter" href="Select_file_descr_watcher.html">
<link title="Shutdown" rel="Chapter" href="Shutdown.html">
<link title="Signal" rel="Chapter" href="Signal.html">
<link title="Signal_manager" rel="Chapter" href="Signal_manager.html">
<link title="Std" rel="Chapter" href="Std.html">
<link title="Syscall" rel="Chapter" href="Syscall.html">
<link title="Thread_pool" rel="Chapter" href="Thread_pool.html">
<link title="Thread_safe" rel="Chapter" href="Thread_safe.html">
<link title="Thread_safe_pipe" rel="Chapter" href="Thread_safe_pipe.html">
<link title="Unix_syscalls" rel="Chapter" href="Unix_syscalls.html">
<link title="Writer" rel="Chapter" href="Writer.html"><title>Scheduler</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Read_write.html" title="Read_write">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Select_file_descr_watcher.html" title="Select_file_descr_watcher">Next</a>
</div>
<h1>Module <a href="type_Scheduler.html">Scheduler</a></h1>
<pre><span class="keyword">module</span> Scheduler: <code class="code">sig</code> <a href="Scheduler.html">..</a> <code class="code">end</code></pre><div class="info module top">
Threading model:
<p>
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 <code class="code">Thread_safe.run_in_async*</code>, which acquires the
lock, does a computation (e.g. fills an ivar), and then runs a "cycle" of Async
computations.<br>
</div>
<hr width="100%">
<pre><span id="TYPEt"><span class="keyword">type</span> <code class="type"></code>t</span> = <code class="type"><a href="Raw_scheduler.html#TYPEt">Raw_scheduler.t</a></code> </pre>
<pre><span id="VALt"><span class="keyword">val</span> t</span> : <code class="type">unit -> <a href="Scheduler.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">t ()</code> returns the async scheduler. If the scheduler hasn't been created yet, this
will create it and acquire the async lock.<br>
</div>
<pre><span id="VALgo"><span class="keyword">val</span> go</span> : <code class="type">?raise_unhandled_exn:bool -> unit -> Core.Std.never_returns</code></pre><div class="info ">
<code class="code">go ?raise_unhandled_exn ()</code> 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 <code class="code">shutdown</code> is called.
<p>
<code class="code">go ()</code> calls <code class="code">handle_signal Sys.sigpipe</code>, which causes the SIGPIPE signal to be
ignored. Low-level syscalls (e.g. write) still raise EPIPE.
<p>
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 <code class="code">~raise_unhandled_exn:true</code>, which
will cause the unhandled exception to be raised to the caller of <code class="code">go ()</code>.<br>
</div>
<pre><span id="VALgo_main"><span class="keyword">val</span> go_main</span> : <code class="type">?raise_unhandled_exn:bool -><br> ?file_descr_watcher:Import.Config.File_descr_watcher.t -><br> main:(unit -> unit) -> unit -> Core.Std.never_returns</code></pre><div class="info ">
<code class="code">go_main</code> is like <code class="code">go</code>, except that one supplies a <code class="code">main</code> function that will be run to
initialize the async computation, and that <code class="code">go_main</code> will fail if any async has been
used prior to <code class="code">go_main</code> being called. Moreover it allows to configure more static
options of the scheduler.<br>
</div>
<pre><span id="TYPEwith_options"><span class="keyword">type</span> <code class="type">'a</code> with_options</span> = <code class="type">?monitor:Import.Monitor.t -> ?priority:Import.Priority.t -> 'a</code> </pre>
<pre><span id="VALwithin_context"><span class="keyword">val</span> within_context</span> : <code class="type">Import.Execution_context.t -> (unit -> 'a) -> ('a, unit) Core.Std.Result.t</code></pre><div class="info ">
<code class="code">within_context context f</code> runs <code class="code">f ()</code> right now with the specified execution
context. If <code class="code">f</code> raises, then the exception is sent to the monitor of <code class="code">context</code>, and
<code class="code">Error ()</code> is returned.<br>
</div>
<pre><span id="VALwithin'"><span class="keyword">val</span> within'</span> : <code class="type">((unit -> 'a Import.Deferred.t) -> 'a Import.Deferred.t)<br> <a href="Scheduler.html#TYPEwith_options">with_options</a></code></pre><div class="info ">
<code class="code">within' f ~monitor ~priority</code> runs <code class="code">f ()</code> right now, with the specified
block group, monitor, and priority set as specified. They will be reset to their
original values when <code class="code">f</code> returns. If <code class="code">f</code> raises, then the result of <code class="code">within'</code> will
never become determined, but the exception will end up in the specified monitor.<br>
</div>
<pre><span id="VALwithin"><span class="keyword">val</span> within</span> : <code class="type">((unit -> unit) -> unit) <a href="Scheduler.html#TYPEwith_options">with_options</a></code></pre><div class="info ">
<code class="code">within</code> is like <code class="code">within'</code>, but doesn't require thunk to return a deferred.<br>
</div>
<pre><span id="VALwithin_v"><span class="keyword">val</span> within_v</span> : <code class="type">((unit -> 'a) -> 'a option) <a href="Scheduler.html#TYPEwith_options">with_options</a></code></pre><div class="info ">
<code class="code">within_v</code> is like <code class="code">within</code>, but allows a value to be returned by <code class="code">f</code>.<br>
</div>
<pre><span id="VALschedule'"><span class="keyword">val</span> schedule'</span> : <code class="type">((unit -> 'a Import.Deferred.t) -> 'a Import.Deferred.t)<br> <a href="Scheduler.html#TYPEwith_options">with_options</a></code></pre><div class="info ">
Just like <code class="code">within'</code>, but instead of running thunk right now, adds
it to the async queue to be run with other async jobs.<br>
</div>
<pre><span id="VALschedule"><span class="keyword">val</span> schedule</span> : <code class="type">((unit -> unit) -> unit) <a href="Scheduler.html#TYPEwith_options">with_options</a></code></pre><div class="info ">
Just like schedule', but doesn't require thunk to return a deferred.<br>
</div>
<pre><span id="VALcycle_start"><span class="keyword">val</span> cycle_start</span> : <code class="type">unit -> Core.Std.Time.t</code></pre><div class="info ">
<code class="code">cycle_start ()</code> returns the result of <code class="code">Time.now ()</code> called at the beginning of
cycle.<br>
</div>
<pre><span id="VALcycle_times"><span class="keyword">val</span> cycle_times</span> : <code class="type">unit -> Core.Std.Time.Span.t Import.Stream.t</code></pre><div class="info ">
<code class="code">cycle_times ()</code> returns a stream that will have one element for each cycle that Async
runs, with the amount of time that the cycle took (as determined by calls to Time.now
at the beginning and end of the cycle).<br>
</div>
<pre><span id="VALreport_long_cycle_times"><span class="keyword">val</span> report_long_cycle_times</span> : <code class="type">?cutoff:Core.Std.Time.Span.t -> unit -> unit</code></pre><div class="info ">
<code class="code">report_long_cycle_times ?cutoff ()</code> sets up something that will print a warning to
stderr whenever there is an async cycle that is too long, as specified by <code class="code">cutoff</code>,
whose default is 1s.<br>
</div>
<pre><span id="VALcycle_count"><span class="keyword">val</span> cycle_count</span> : <code class="type">unit -> int</code></pre><div class="info ">
<code class="code">cycle_count ()</code> returns the total number of async cycles that have happened.<br>
</div>
<pre><span id="VALforce_current_cycle_to_end"><span class="keyword">val</span> force_current_cycle_to_end</span> : <code class="type">unit -> unit</code></pre><div class="info ">
<code class="code">force_current_cycle_to_end ()</code> 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.<br>
</div>
<pre><span id="VALis_running"><span class="keyword">val</span> is_running</span> : <code class="type">unit -> bool</code></pre><div class="info ">
<code class="code">is_running ()</code> returns true if the scheduler has been started.<br>
</div>
<pre><span id="VALset_max_num_jobs_per_priority_per_cycle"><span class="keyword">val</span> set_max_num_jobs_per_priority_per_cycle</span> : <code class="type">int -> unit</code></pre><div class="info ">
<code class="code">set_max_num_jobs_per_priority_per_cycle int</code> sets the maximum number of jobs that
will be done at each priority within each async cycle. The default is <code class="code">500</code>.<br>
</div>
<pre><code><span id="TYPEfolder"><span class="keyword">type</span> <code class="type">'b</code> folder</span> = {</code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTfolder.folder">folder</span> : <code class="type">'a. 'b -> <a href="Scheduler.html#TYPEt">t</a> -> (<a href="Scheduler.html#TYPEt">t</a>, 'a) Core.Std.Field.t -> 'b</code>;</code></td>
</tr></table>
}
<div class="info ">
<code class="code">fold_fields ~init folder</code> folds <code class="code">folder</code> over each field in the scheduler. The
fields themselves are not exposed -- <code class="code">folder</code> 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.<br>
</div>
<pre><span id="VALfold_fields"><span class="keyword">val</span> fold_fields</span> : <code class="type">init:'b -> 'b <a href="Scheduler.html#TYPEfolder">folder</a> -> 'b</code></pre>
<pre><span id="VALis_ready_to_initialize"><span class="keyword">val</span> is_ready_to_initialize</span> : <code class="type">unit -> bool</code></pre>
<pre><span id="VALreset_in_forked_process"><span class="keyword">val</span> reset_in_forked_process</span> : <code class="type">unit -> unit</code></pre><div class="info ">
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 <code class="code">reset_in_forked_process</code> at the
start of execution in the child process. After that, the child can do async stuff and
then start the async scheduler.<br>
</div>
<pre><span id="VALsexp_of_t"><span class="keyword">val</span> sexp_of_t</span> : <code class="type"><a href="Scheduler.html#TYPEt">t</a> -> Sexplib.Sexp.t</code></pre><br>
<code class="code">t ()</code> returns the async scheduler. If the scheduler hasn't been created yet, this
will create it and acquire the async lock.<br>
<br>
<code class="code">go ?raise_unhandled_exn ()</code> 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 <code class="code">shutdown</code> is called.
<p>
<code class="code">go ()</code> calls <code class="code">handle_signal Sys.sigpipe</code>, which causes the SIGPIPE signal to be
ignored. Low-level syscalls (e.g. write) still raise EPIPE.
<p>
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 <code class="code">~raise_unhandled_exn:true</code>, which
will cause the unhandled exception to be raised to the caller of <code class="code">go ()</code>.<br>
<br>
<code class="code">go_main</code> is like <code class="code">go</code>, except that one supplies a <code class="code">main</code> function that will be run to
initialize the async computation, and that <code class="code">go_main</code> will fail if any async has been
used prior to <code class="code">go_main</code> being called. Moreover it allows to configure more static
options of the scheduler.<br>
<br>
<code class="code">within_context context f</code> runs <code class="code">f ()</code> right now with the specified execution
context. If <code class="code">f</code> raises, then the exception is sent to the monitor of <code class="code">context</code>, and
<code class="code">Error ()</code> is returned.<br>
<br>
<code class="code">within' f ~monitor ~priority</code> runs <code class="code">f ()</code> right now, with the specified
block group, monitor, and priority set as specified. They will be reset to their
original values when <code class="code">f</code> returns. If <code class="code">f</code> raises, then the result of <code class="code">within'</code> will
never become determined, but the exception will end up in the specified monitor.<br>
<br>
<code class="code">within</code> is like <code class="code">within'</code>, but doesn't require thunk to return a deferred.<br>
<br>
<code class="code">within_v</code> is like <code class="code">within</code>, but allows a value to be returned by <code class="code">f</code>.<br>
<br>
Just like <code class="code">within'</code>, but instead of running thunk right now, adds
it to the async queue to be run with other async jobs.<br>
<br>
Just like schedule', but doesn't require thunk to return a deferred.<br>
<br>
<code class="code">cycle_start ()</code> returns the result of <code class="code">Time.now ()</code> called at the beginning of
cycle.<br>
<br>
<code class="code">cycle_times ()</code> returns a stream that will have one element for each cycle that Async
runs, with the amount of time that the cycle took (as determined by calls to Time.now
at the beginning and end of the cycle).<br>
<br>
<code class="code">report_long_cycle_times ?cutoff ()</code> sets up something that will print a warning to
stderr whenever there is an async cycle that is too long, as specified by <code class="code">cutoff</code>,
whose default is 1s.<br>
<br>
<code class="code">cycle_count ()</code> returns the total number of async cycles that have happened.<br>
<br>
<code class="code">force_current_cycle_to_end ()</code> 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.<br>
<br>
<code class="code">is_running ()</code> returns true if the scheduler has been started.<br>
<br>
<code class="code">set_max_num_jobs_per_priority_per_cycle int</code> sets the maximum number of jobs that
will be done at each priority within each async cycle. The default is <code class="code">500</code>.<br>
<br>
<code class="code">fold_fields ~init folder</code> folds <code class="code">folder</code> over each field in the scheduler. The
fields themselves are not exposed -- <code class="code">folder</code> 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.<br>
<br>
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 <code class="code">reset_in_forked_process</code> at the
start of execution in the child process. After that, the child can do async stuff and
then start the async scheduler.<br>
</body></html>
