mirror of
https://github.com/c-cube/linol.git
synced 2025-12-07 11:45:43 -05:00
22 lines
8.2 KiB
HTML
22 lines
8.2 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Lwt_pool (lwt.Lwt_pool)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.2"/><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">lwt</a> » Lwt_pool</nav><header class="odoc-preamble"><h1>Module <code><span>Lwt_pool</span></code></h1><p>External resource pools.</p><p>This module provides an abstraction for managing collections of resources. One example use case is for managing a pool of database connections, where instead of establishing a new connection each time you need one (which is expensive), you can keep a pool of opened connections and reuse ones that are free.</p><p>It also provides the capability of:</p><ul><li>specifying the maximum number of resources that the pool can manage simultaneously,</li><li>checking whether a resource is still valid before/after use, and</li><li>performing cleanup logic before dropping a resource.</li></ul><p>The following example illustrates how it is used with an imaginary <code>Db</code> module:</p><pre class="language-ocaml"><code>let uri = "postgresql://localhost:5432"
|
||
|
||
(* Create a database connection pool with max size of 10. *)
|
||
let pool =
|
||
Lwt_pool.create 10
|
||
~dispose:(fun connection -> Db.close connection |> Lwt.return)
|
||
(fun () -> Db.connect uri |> Lwt.return)
|
||
|
||
(* Use the pool in queries. *)
|
||
let create_user name =
|
||
Lwt_pool.use pool (fun connection ->
|
||
connection
|
||
|> Db.insert "users" [("name", name)]
|
||
|> Lwt.return
|
||
)</code></pre><p>Note that this is <em>not</em> intended to keep a pool of system threads. If you want to have such pool, consider using <a href="../Lwt_preemptive/index.html"><code>Lwt_preemptive</code></a>.</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> <span>'a t</span></span></code></div><div class="spec-doc"><p>A pool containing elements of type <code>'a</code>.</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>int <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?validate</span>:<span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>bool <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?check</span>:<span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span>(<span>bool <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span> unit)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?dispose</span>:<span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span>unit <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>create n ?check ?validate ?dispose f</code> creates a new pool with at most <code>n</code> elements. <code>f</code> is used to create a new pool element. Elements are created on demand and re-used until disposed of.</p><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">validate</span> <p>is called each time a pool element is accessed by <a href="#val-use"><code>use</code></a>, before the element is provided to <a href="#val-use"><code>use</code></a>'s callback. If <code>validate element</code> resolves to <code>true</code> the element is considered valid and is passed to the callback for use as-is. If <code>validate element</code> resolves to <code>false</code> the tested pool element is passed to <code>dispose</code> then dropped, with a new one is created to take <code>element</code>'s place in the pool. <code>validate</code> is available since Lwt 3.2.0.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">check</span> <p>is called after the resolution of <a href="#val-use"><code>use</code></a>'s callback when the resolution is a failed promise. <code>check element is_ok</code> must call <code>is_ok</code> exactly once with <code>true</code> if <code>element</code> is still valid and <code>false</code> otherwise. If <code>check</code> calls <code>is_ok false</code> then <code>dispose</code> will be run on <code>element</code> and the element will not be returned to the pool.</p></li></ul><ul class="at-tags"><li class="parameter"><span class="at-tag">parameter</span> <span class="value">dispose</span> <p>is used as described above and by <a href="#val-clear"><code>clear</code></a> to dispose of all elements in a pool. <code>dispose</code> is <b>not</b> guaranteed to be called on the elements in a pool when the pool is garbage collected. <a href="#val-clear"><code>clear</code></a> should be used if the elements of the pool need to be explicitly disposed of.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-use"><a href="#val-use" class="anchor"></a><code><span><span class="keyword">val</span> use : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>use p f</code> requests one free element of the pool <code>p</code> and gives it to the function <code>f</code>. The element is put back into the pool after the promise created by <code>f</code> completes.</p><p>In the case that <code>p</code> is exhausted and the maximum number of elements is reached, <code>use</code> will wait until one becomes free.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-clear"><a href="#val-clear" class="anchor"></a><code><span><span class="keyword">val</span> clear : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>unit <a href="../Lwt/index.html#type-t">Lwt.t</a></span></span></code></div><div class="spec-doc"><p><code>clear p</code> will clear all elements in <code>p</code>, calling the <code>dispose</code> function associated with <code>p</code> on each of the cleared elements. Any elements from <code>p</code> which are currently in use will be disposed of once they are released.</p><p>The next call to <code>use p</code> after <code>clear p</code> guarantees a freshly created pool element.</p><p>Disposals are performed sequentially in an undefined order.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.2.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-wait_queue_length"><a href="#val-wait_queue_length" class="anchor"></a><code><span><span class="keyword">val</span> wait_queue_length : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>wait_queue_length p</code> returns the number of <a href="#val-use"><code>use</code></a> requests currently waiting for an element of the pool <code>p</code> to become available.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 3.2.0</li></ul></div></div></div></body></html>
|