mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-06 11:15:38 -05:00
deploy: d50c227578
This commit is contained in:
c-cube
parent
8d23a673c0
commit
5ac15418d0
6 changed files with 122 additions and 1 deletions
2
backoff/Backoff/index.html
Normal file
2
backoff/Backoff/index.html
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Backoff (backoff.Backoff)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.0.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">Index</a> » <a href="../index.html">backoff</a> » Backoff</nav><header class="odoc-preamble"><h1>Module <code><span>Backoff</span></code></h1><p>Randomized exponential backoff mechanism.</p></header><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code></div><div class="spec-doc"><p>Type of backoff values.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-max_wait_log"><a href="#val-max_wait_log" class="anchor"></a><code><span><span class="keyword">val</span> max_wait_log : int</span></code></div><div class="spec-doc"><p>Logarithm of the maximum allowed value for wait.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create"><a href="#val-create" class="anchor"></a><code><span><span class="keyword">val</span> create : <span><span class="optlabel">?lower_wait_log</span>:int <span class="arrow">-></span></span> <span><span class="optlabel">?upper_wait_log</span>:int <span class="arrow">-></span></span> <span>unit <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>create</code> creates a backoff value. <code>upper_wait_log</code>, <code>lower_wait_log</code> override the logarithmic upper and lower bound on the number of spins executed by <a href="#val-once"><code>once</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-default"><a href="#val-default" class="anchor"></a><code><span><span class="keyword">val</span> default : <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>default</code> is equivalent to <code>create ()</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-once"><a href="#val-once" class="anchor"></a><code><span><span class="keyword">val</span> once : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>once b</code> executes one random wait and returns a new backoff with logarithm of the current maximum value incremented unless it is already at <code>upper_wait_log</code> of <code>b</code>.</p><p>Note that this uses the default Stdlib <code>Random</code> per-domain generator.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-reset"><a href="#val-reset" class="anchor"></a><code><span><span class="keyword">val</span> reset : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> <a href="#type-t">t</a></span></code></div><div class="spec-doc"><p><code>reset b</code> returns a backoff equivalent to <code>b</code> except with current value set to the <code>lower_wait_log</code> of <code>b</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_wait_log"><a href="#val-get_wait_log" class="anchor"></a><code><span><span class="keyword">val</span> get_wait_log : <span><a href="#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>get_wait_log b</code> returns logarithm of the maximum value of wait for next <a href="#val-once"><code>once</code></a>.</p></div></div></div></body></html>
|
||||||
7
backoff/_doc-dir/CHANGES.md
Normal file
7
backoff/_doc-dir/CHANGES.md
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
## 0.1.1
|
||||||
|
|
||||||
|
- Ported to 4.12 and optimized for size (@polytypic)
|
||||||
|
|
||||||
|
## 0.1.0
|
||||||
|
|
||||||
|
- Initial version based on backoff from kcas (@lyrm, @polytypic)
|
||||||
16
backoff/_doc-dir/LICENSE.md
Normal file
16
backoff/_doc-dir/LICENSE.md
Normal file
|
|
@ -0,0 +1,16 @@
|
||||||
|
Copyright (c) 2015, Théo Laurent <theo.laurent@ens.fr>
|
||||||
|
Copyright (c) 2016, KC Sivaramakrishnan <kc@kcsrk.info>
|
||||||
|
Copyright (c) 2021, Sudha Parimala <sudharg247@gmail.com>
|
||||||
|
Copyright (c) 2023, Vesa Karvonen <vesa.a.j.k@gmail.com>
|
||||||
|
|
||||||
|
Permission to use, copy, modify, and/or distribute this software for any
|
||||||
|
purpose with or without fee is hereby granted, provided that the above
|
||||||
|
copyright notice and this permission notice appear in all copies.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||||||
|
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||||||
|
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||||||
|
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||||
|
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||||
|
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||||
|
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||||
94
backoff/_doc-dir/README.md
Normal file
94
backoff/_doc-dir/README.md
Normal file
|
|
@ -0,0 +1,94 @@
|
||||||
|
[API reference](https://ocaml-multicore.github.io/backoff/doc/backoff/Backoff/index.html)
|
||||||
|
|
||||||
|
# backoff - exponential backoff mechanism
|
||||||
|
|
||||||
|
**backoff** provides an
|
||||||
|
[exponential backoff mechanism](https://en.wikipedia.org/wiki/Exponential_backoff)
|
||||||
|
[1]. It reduces contention by making a domain back off after failing an
|
||||||
|
operation contested by another domain, like acquiring a lock or performing a
|
||||||
|
`CAS` operation.
|
||||||
|
|
||||||
|
## About contention
|
||||||
|
|
||||||
|
Contention is what happens when multiple CPU cores try to access the same
|
||||||
|
location(s) in parallel. Let's take the example of multiple CPU cores trying to
|
||||||
|
perform a `CAS` on the same location at the same time. Only one is going to
|
||||||
|
success at each round of retries. By writing on a shared location, it
|
||||||
|
invalidates all other CPUs' caches. So at each round each CPU will have to read
|
||||||
|
the memory location again, leading to quadratic O(n²) bus traffic.
|
||||||
|
|
||||||
|
## Exponential backoff
|
||||||
|
|
||||||
|
Failing to access a shared resource means there is contention: some other CPU
|
||||||
|
cores are trying to access it at the same time. To avoid quadratic bus traffic,
|
||||||
|
the idea exploited by exponential backoff is to make each CPU core wait (spin) a
|
||||||
|
random bit before retrying. This way, they will try to access the resource at a
|
||||||
|
different time: that not only strongly decreases bus traffic but that also gets
|
||||||
|
them a better chance to get the resource, at they probably will compete for it
|
||||||
|
against less other CPU cores. Failing again probably means contention is high,
|
||||||
|
and they need to wait longer. In fact, each consecutive fail of a single CPU
|
||||||
|
core will make it wait twice longer (_exponential_ backoff !).
|
||||||
|
|
||||||
|
Obviously, they cannot wait forever: there is an upper limit on the number of
|
||||||
|
times the initial waiting time can be doubled (see [Tuning](#tuning)), but
|
||||||
|
intuitively, a good waiting time should be at least around the time the
|
||||||
|
contested operation takes (in our example, the operation is a CAS) and at most a
|
||||||
|
few times that amount.
|
||||||
|
|
||||||
|
## Tuning
|
||||||
|
|
||||||
|
For better performance, backoff can be tuned. `Backoff.create` function has two
|
||||||
|
optional arguments for that: `upper_wait_log` and `lower_wait_log` that defines
|
||||||
|
the logarithmic upper and lower bound on the number of spins executed by
|
||||||
|
{!once}.
|
||||||
|
|
||||||
|
## Drawbacks
|
||||||
|
|
||||||
|
This mechanism has some drawbacks. First, it adds some delays: for example, when
|
||||||
|
a domain releases a contended lock, another domain, that has backed off after
|
||||||
|
failing acquiring it, will still have to finish its back-off loop before
|
||||||
|
retrying. Second, this increases any unfairness: any other thread that arrives
|
||||||
|
at that time or that has failed acquiring the lock for a lesser number of times
|
||||||
|
is more likely to acquire it as it will probably have a shorter waiting time.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
To illustrate how to use backoff, here is a small implementation of
|
||||||
|
`test and test-and-set` spin lock [2].
|
||||||
|
|
||||||
|
```ocaml
|
||||||
|
type t = bool Atomic.t
|
||||||
|
|
||||||
|
let create () = Atomic.make false
|
||||||
|
|
||||||
|
let rec acquire ?(backoff = Backoff.detault) t =
|
||||||
|
if Atomic.get t then begin
|
||||||
|
Domain.cpu_relax ();
|
||||||
|
acquire ~backoff t
|
||||||
|
end
|
||||||
|
else if not (Atomic.compare_and_set t false true) then
|
||||||
|
acquire ~backoff:(Backoff.once backoff) t
|
||||||
|
|
||||||
|
let release t = Atomic.set t false
|
||||||
|
```
|
||||||
|
|
||||||
|
This implementation can also be found [here](bench/taslock.ml), as well as a
|
||||||
|
small [benchmark](bench/test_tas.ml) to compare it to the same TAS lock but
|
||||||
|
without backoff. It can be launched with:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
dune exec ./bench/test_tas.exe > bench.data
|
||||||
|
```
|
||||||
|
|
||||||
|
and displayed (on linux) with:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
gnuplot -p -e 'plot for [col=2:4] "bench.data" using 1:col with lines title columnheader'
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
[1] Adaptive backoff synchronization techniques, A. Agarwal, M. Cherian (1989)
|
||||||
|
|
||||||
|
[2] Dynamic Decentralized Cache Schemes for MIMD Parallel Processors, L.Rudolf,
|
||||||
|
Z.Segall (1984)
|
||||||
2
backoff/index.html
Normal file
2
backoff/index.html
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>index (backoff.index)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.0.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">Index</a> » backoff</nav><header class="odoc-preamble"><h1 id="package-backoff"><a href="#package-backoff" class="anchor"></a>Package backoff <nav><a type="text/plain; charset=UTF-8" href="_doc-dir/CHANGES.md">changes</a> <a href="#package_info">more…</a></nav></h1><ul class="modules"><li><a href="Backoff/index.html"><code>Backoff</code></a> <span class="synopsis">Randomized exponential backoff mechanism.</span></li></ul></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#package_info">Package info</a></li></ul></nav></div><div class="odoc-content"><h2 id="package_info"><a href="#package_info" class="anchor"></a>Package info</h2><table class="package info"><tr id="info-changes-files"><td><a href="#info-changes-files" aria-hidden="true" class="anchor"></a>changes-files</td><td><ul><li><a type="text/plain; charset=UTF-8" href="_doc-dir/CHANGES.md">CHANGES.md</a></li></ul></td></tr><tr id="info-license-files"><td><a href="#info-license-files" aria-hidden="true" class="anchor"></a>license-files</td><td><ul><li><a type="text/plain; charset=UTF-8" href="_doc-dir/LICENSE.md">LICENSE.md</a></li></ul></td></tr><tr id="info-readme-files"><td><a href="#info-readme-files" aria-hidden="true" class="anchor"></a>readme-files</td><td><ul><li><a type="text/plain; charset=UTF-8" href="_doc-dir/README.md">README.md</a></li></ul></td></tr></table></div></body></html>
|
||||||
|
|
@ -1,2 +1,2 @@
|
||||||
<!DOCTYPE html>
|
<!DOCTYPE html>
|
||||||
<html><head><meta charset="utf-8"><meta name="generator" content="odig v0.0.9"><meta name="viewport" content="width=device-width, initial-scale=1.0"><link rel="stylesheet" type="text/css" media="screen, print" href="_odoc-theme/odoc.css"><title>_opam</title></head><body class="odoc"><nav class="odoc-nav">🐫</nav><header class="odoc-preamble"><h1>OCaml package documentation</h1><p>Browse <a href="#by-name">by name</a>, <a href="#by-tag">by tag</a>, the <a href="ocaml/Stdlib/index.html#modules">standard library</a> and the <a href="https://ocaml.org/manual/">OCaml manual</a> (online, latest version).</p><p><small>Generated for <code>/home/runner/work/moonpool/moonpool/_opam/lib</code></small></p></header><nav class="odoc-toc"><ul><li><a href="ocaml/Stdlib/index.html#modules">OCaml standard library</a></li><li><a href="https://ocaml.org/manual/">OCaml manual</a></li><li><a href="#by-name">Packages by name</a></li><li><a href="#by-tag">Packages by tag</a></li></ul></nav><div class="odoc-content"><h2 id="by-name"><a href="#by-name" aria-hidden="true" class="anchor"></a>Packages by name</h2><div class="by-name"><nav><a href="#name-e">e</a><a href="#name-l">l</a><a href="#name-m">m</a><a href="#name-o">o</a><a href="#name-p">p</a><a href="#name-t">t</a></nav><h3 id="name-e"><a href="#name-e" aria-hidden="true" class="anchor"></a>e</h3><ol class="packages"><li id="package-either"><a href="#package-either" aria-hidden="true" class="anchor"></a><a href="either/index.html">either</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-l"><a href="#name-l" aria-hidden="true" class="anchor"></a>l</h3><ol class="packages"><li id="package-lwt"><a href="#package-lwt" aria-hidden="true" class="anchor"></a><a href="lwt/index.html">lwt</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-m"><a href="#name-m" aria-hidden="true" class="anchor"></a>m</h3><ol class="packages"><li id="package-moonpool"><a href="#package-moonpool" aria-hidden="true" class="anchor"></a><a href="moonpool/index.html">moonpool</a> <span class="version"></span> <span class="synopsis"></span></li><li id="package-moonpool-lwt"><a href="#package-moonpool-lwt" aria-hidden="true" class="anchor"></a><a href="moonpool-lwt/index.html">moonpool-lwt</a> <span class="version"></span> <span class="synopsis"></span></li><li id="package-multicore-magic"><a href="#package-multicore-magic" aria-hidden="true" class="anchor"></a><a href="multicore-magic/index.html">multicore-magic</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-o"><a href="#name-o" aria-hidden="true" class="anchor"></a>o</h3><ol class="packages"><li id="package-ocaml"><a href="#package-ocaml" aria-hidden="true" class="anchor"></a><a href="ocaml/index.html">ocaml</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-p"><a href="#name-p" aria-hidden="true" class="anchor"></a>p</h3><ol class="packages"><li id="package-picos"><a href="#package-picos" aria-hidden="true" class="anchor"></a><a href="picos/index.html">picos</a> <span class="version"></span> <span class="synopsis"></span></li><li id="package-picos_std"><a href="#package-picos_std" aria-hidden="true" class="anchor"></a><a href="picos_std/index.html">picos_std</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-t"><a href="#name-t" aria-hidden="true" class="anchor"></a>t</h3><ol class="packages"><li id="package-thread-local-storage"><a href="#package-thread-local-storage" aria-hidden="true" class="anchor"></a><a href="thread-local-storage/index.html">thread-local-storage</a> <span class="version"></span> <span class="synopsis"></span></li></ol></div><h2 id="by-tag"><a href="#by-tag" aria-hidden="true" class="anchor"></a>Packages by tag</h2><div class="by-tag"><nav><table></table></nav></div></div></body></html>
|
<html><head><meta charset="utf-8"><meta name="generator" content="odig v0.0.9"><meta name="viewport" content="width=device-width, initial-scale=1.0"><link rel="stylesheet" type="text/css" media="screen, print" href="_odoc-theme/odoc.css"><title>_opam</title></head><body class="odoc"><nav class="odoc-nav">🐫</nav><header class="odoc-preamble"><h1>OCaml package documentation</h1><p>Browse <a href="#by-name">by name</a>, <a href="#by-tag">by tag</a>, the <a href="ocaml/Stdlib/index.html#modules">standard library</a> and the <a href="https://ocaml.org/manual/">OCaml manual</a> (online, latest version).</p><p><small>Generated for <code>/home/runner/work/moonpool/moonpool/_opam/lib</code></small></p></header><nav class="odoc-toc"><ul><li><a href="ocaml/Stdlib/index.html#modules">OCaml standard library</a></li><li><a href="https://ocaml.org/manual/">OCaml manual</a></li><li><a href="#by-name">Packages by name</a></li><li><a href="#by-tag">Packages by tag</a></li></ul></nav><div class="odoc-content"><h2 id="by-name"><a href="#by-name" aria-hidden="true" class="anchor"></a>Packages by name</h2><div class="by-name"><nav><a href="#name-b">b</a><a href="#name-e">e</a><a href="#name-l">l</a><a href="#name-m">m</a><a href="#name-o">o</a><a href="#name-p">p</a><a href="#name-t">t</a></nav><h3 id="name-b"><a href="#name-b" aria-hidden="true" class="anchor"></a>b</h3><ol class="packages"><li id="package-backoff"><a href="#package-backoff" aria-hidden="true" class="anchor"></a><a href="backoff/index.html">backoff</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-e"><a href="#name-e" aria-hidden="true" class="anchor"></a>e</h3><ol class="packages"><li id="package-either"><a href="#package-either" aria-hidden="true" class="anchor"></a><a href="either/index.html">either</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-l"><a href="#name-l" aria-hidden="true" class="anchor"></a>l</h3><ol class="packages"><li id="package-lwt"><a href="#package-lwt" aria-hidden="true" class="anchor"></a><a href="lwt/index.html">lwt</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-m"><a href="#name-m" aria-hidden="true" class="anchor"></a>m</h3><ol class="packages"><li id="package-moonpool"><a href="#package-moonpool" aria-hidden="true" class="anchor"></a><a href="moonpool/index.html">moonpool</a> <span class="version"></span> <span class="synopsis"></span></li><li id="package-moonpool-lwt"><a href="#package-moonpool-lwt" aria-hidden="true" class="anchor"></a><a href="moonpool-lwt/index.html">moonpool-lwt</a> <span class="version"></span> <span class="synopsis"></span></li><li id="package-multicore-magic"><a href="#package-multicore-magic" aria-hidden="true" class="anchor"></a><a href="multicore-magic/index.html">multicore-magic</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-o"><a href="#name-o" aria-hidden="true" class="anchor"></a>o</h3><ol class="packages"><li id="package-ocaml"><a href="#package-ocaml" aria-hidden="true" class="anchor"></a><a href="ocaml/index.html">ocaml</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-p"><a href="#name-p" aria-hidden="true" class="anchor"></a>p</h3><ol class="packages"><li id="package-picos"><a href="#package-picos" aria-hidden="true" class="anchor"></a><a href="picos/index.html">picos</a> <span class="version"></span> <span class="synopsis"></span></li><li id="package-picos_std"><a href="#package-picos_std" aria-hidden="true" class="anchor"></a><a href="picos_std/index.html">picos_std</a> <span class="version"></span> <span class="synopsis"></span></li></ol><h3 id="name-t"><a href="#name-t" aria-hidden="true" class="anchor"></a>t</h3><ol class="packages"><li id="package-thread-local-storage"><a href="#package-thread-local-storage" aria-hidden="true" class="anchor"></a><a href="thread-local-storage/index.html">thread-local-storage</a> <span class="version"></span> <span class="synopsis"></span></li></ol></div><h2 id="by-tag"><a href="#by-tag" aria-hidden="true" class="anchor"></a>Packages by tag</h2><div class="by-tag"><nav><table></table></nav></div></div></body></html>
|
||||||
Loading…
Add table
Reference in a new issue