313 lines
8.4 KiB
HTML
313 lines
8.4 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
|
|
<head>
|
|
<title>timerwheel</title>
|
|
<link rel="stylesheet" href="ldoc.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
|
|
<div id="container">
|
|
|
|
<div id="product">
|
|
<div id="product_logo"></div>
|
|
<div id="product_name"><big><b></b></big></div>
|
|
<div id="product_description"></div>
|
|
</div> <!-- id="product" -->
|
|
|
|
|
|
<div id="main">
|
|
|
|
|
|
<!-- Menu -->
|
|
|
|
<div id="navigation">
|
|
<br/>
|
|
<h1>timerwheel.lua</h1>
|
|
|
|
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li><a href="#Functions">Functions</a></li>
|
|
</ul>
|
|
|
|
|
|
<h2>Modules</h2>
|
|
<ul class="nowrap">
|
|
<li><strong>timerwheel</strong></li>
|
|
</ul>
|
|
<h2>Topics</h2>
|
|
<ul class="">
|
|
<li><a href="topics/readme.md.html">readme</a></li>
|
|
</ul>
|
|
|
|
</div>
|
|
|
|
<div id="content">
|
|
|
|
<h1>Module <code>timerwheel</code></h1>
|
|
<p>Timer wheel implementation</p>
|
|
|
|
<p> Efficient timer for timeout related timers: fast insertion, deletion, and
|
|
execution (all as O(1) implemented), but with lesser precision.</p>
|
|
<p> This module will not provide the timer/runloop itself. Use your own runloop
|
|
and call <a href="index.html#wheel:step">wheel:step</a> to check and execute timers.</p>
|
|
|
|
<p> Implementation:
|
|
Consider a stack of rings, a timer beyond the current ring size is in the
|
|
next ring (or beyond). Precision is based on a slot with a specific size.</p>
|
|
|
|
<p> The code explicitly avoids using <a href="https://www.lua.org/manual/5.1/manual.html#pdf-pairs">pairs</a>, <a href="https://www.lua.org/manual/5.1/manual.html#pdf-ipairs">ipairs</a> and <a href="https://www.lua.org/manual/5.1/manual.html#pdf-next">next</a> to ensure JIT
|
|
compilation when using LuaJIT</p>
|
|
|
|
|
|
<h2><a href="#Functions">Functions</a></h2>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#new">new (opts)</a></td>
|
|
<td class="summary">Creates a new timer wheel.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#wheel:cancel">wheel:cancel (id)</a></td>
|
|
<td class="summary">Cancels a timer.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#wheel:count">wheel:count ()</a></td>
|
|
<td class="summary">Gets the number of timers.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#wheel:peek">wheel:peek ([max_ahead])</a></td>
|
|
<td class="summary">Looks up the next expiring timer.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#wheel:set">wheel:set (expire_in, cb, arg)</a></td>
|
|
<td class="summary">Sets a timer.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#wheel:step">wheel:step ()</a></td>
|
|
<td class="summary">Checks and executes timers.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br/>
|
|
<br/>
|
|
|
|
|
|
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
|
|
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "new"></a>
|
|
<strong>new (opts)</strong>
|
|
</dt>
|
|
<dd>
|
|
Creates a new timer wheel.
|
|
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">opts</span> the options table
|
|
<ul>
|
|
<li><span class="parameter">precision</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
the precision of the timer wheel in seconds (slot size),
|
|
(<em>default</em> 0.050)
|
|
</li>
|
|
<li><span class="parameter">ringsize</span>
|
|
<span class="types"><span class="type">int</span></span>
|
|
number of slots in each ring, defaults to 72000 (1
|
|
hour span, with <code>precision == 0.050</code>)
|
|
(<em>optional</em>)
|
|
</li>
|
|
<li><span class="parameter">now</span>
|
|
<span class="types"><span class="type">function</span></span>
|
|
a function returning the curent time in seconds. Defaults
|
|
to <code>ngx.now</code> or <code>luasocket.gettime</code> if available.
|
|
(<em>optional</em>)
|
|
</li>
|
|
<li><span class="parameter">err_handler</span>
|
|
<span class="types"><span class="type">function</span></span>
|
|
a function to use as error handler in an <a href="https://www.lua.org/manual/5.1/manual.html#pdf-xpcall">xpcall</a> when
|
|
executing the callback. The default will write the stacktrace to <code>stderr</code>.
|
|
(<em>optional</em>)
|
|
</li>
|
|
</li></ul>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">wheel</span></span>
|
|
the timerwheel object
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "wheel:cancel"></a>
|
|
<strong>wheel:cancel (id)</strong>
|
|
</dt>
|
|
<dd>
|
|
Cancels a timer.
|
|
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">id</span>
|
|
<span class="types"><span class="type">int</span></span>
|
|
the timer id to cancel
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<code>true</code> if cancelled, <code>false</code> if not found
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "wheel:count"></a>
|
|
<strong>wheel:count ()</strong>
|
|
</dt>
|
|
<dd>
|
|
Gets the number of timers.
|
|
|
|
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">int</span></span>
|
|
number of timers
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "wheel:peek"></a>
|
|
<strong>wheel:peek ([max_ahead])</strong>
|
|
</dt>
|
|
<dd>
|
|
Looks up the next expiring timer.
|
|
Note: traverses the wheel, O(n) operation!
|
|
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">max_ahead</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
maximum time (in seconds)
|
|
to look ahead
|
|
(<em>optional</em>)
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">number</span></span>
|
|
number of seconds until next timer expires (can be negative), or
|
|
'nil' if there is no timer from now to <code>max_ahead</code>
|
|
</ol>
|
|
|
|
|
|
|
|
<h3>Usage:</h3>
|
|
<ul>
|
|
<pre class="example"><span class="keyword">local</span> t = wheel:peek(<span class="number">10</span>)
|
|
<span class="keyword">if</span> t <span class="keyword">then</span>
|
|
<span class="global">print</span>(<span class="string">"next timer expires in "</span>, t,<span class="string">" seconds"</span>)
|
|
<span class="keyword">else</span>
|
|
<span class="global">print</span>(<span class="string">"no timer scheduled for the next 10 seconds"</span>)
|
|
<span class="keyword">end</span></pre>
|
|
</ul>
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "wheel:set"></a>
|
|
<strong>wheel:set (expire_in, cb, arg)</strong>
|
|
</dt>
|
|
<dd>
|
|
Sets a timer.
|
|
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">expire_in</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
in how many seconds should the timer expire
|
|
</li>
|
|
<li><span class="parameter">cb</span>
|
|
<span class="types"><span class="type">function</span></span>
|
|
callback function to execute upon expiring (NOTE: the
|
|
callback will run within an <a href="https://www.lua.org/manual/5.1/manual.html#pdf-xpcall">xpcall</a>)
|
|
</li>
|
|
<li><span class="parameter">arg</span>
|
|
parameter to be passed to <code>cb</code> when executing
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">int</span></span>
|
|
the id of the newly set timer
|
|
</ol>
|
|
|
|
|
|
|
|
<h3>Usage:</h3>
|
|
<ul>
|
|
<pre class="example"><span class="keyword">local</span> cb = <span class="keyword">function</span>(arg)
|
|
<span class="global">print</span>(<span class="string">"timer executed with: "</span>, arg) <span class="comment">--> "timer executed with: hello world"
|
|
</span><span class="keyword">end</span>
|
|
<span class="keyword">local</span> id = wheel:set(<span class="number">5</span>, cb, <span class="string">"hello world"</span>)
|
|
|
|
<span class="comment">-- do stuff here, while regularly calling <code>wheel:step()</code>
|
|
</span>
|
|
wheel:cancel(id) <span class="comment">-- cancel the timer again</span></pre>
|
|
</ul>
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "wheel:step"></a>
|
|
<strong>wheel:step ()</strong>
|
|
</dt>
|
|
<dd>
|
|
Checks and executes timers.
|
|
Call this function (at least) every <code>precision</code> seconds.
|
|
|
|
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<code>true</code>
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
</div> <!-- id="content" -->
|
|
</div> <!-- id="main" -->
|
|
<div id="about">
|
|
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
|
|
<i style="float:right;">Last updated 2022-11-03 17:31:27 </i>
|
|
</div> <!-- id="about" -->
|
|
</div> <!-- id="container" -->
|
|
</body>
|
|
</html>
|