summaryrefslogtreecommitdiff
path: root/Lua API.html
diff options
context:
space:
mode:
authorAlexander Gavrilov2012-08-23 19:27:12 +0400
committerAlexander Gavrilov2012-08-23 19:27:28 +0400
commitc6c5ad56c9b4421e1bf8a5bc2f38323734a9d2eb (patch)
treed81ff429044aa2cfd70f901c615c64db48f5ad3e /Lua API.html
parent7046a6abbc157dd0102189e7dd6769183196766f (diff)
downloaddfhack-c6c5ad56c9b4421e1bf8a5bc2f38323734a9d2eb.tar.gz
dfhack-c6c5ad56c9b4421e1bf8a5bc2f38323734a9d2eb.tar.bz2
dfhack-c6c5ad56c9b4421e1bf8a5bc2f38323734a9d2eb.tar.xz
Track lua event listener count, and let the C++ host know.
This allows completely avoiding the call overhead if there are none. The downside is that the event object now has to be a userdata with lots of metamethods.
Diffstat (limited to 'Lua API.html')
-rw-r--r--Lua API.html14
1 files changed, 10 insertions, 4 deletions
diff --git a/Lua API.html b/Lua API.html
index 0f1ecc3b..c4ab9c8c 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -1596,8 +1596,8 @@ Using <tt class="docutils literal">timeout_active(id,nil)</tt> cancels the timer
</ul>
<div class="section" id="event-type">
<h3><a class="toc-backref" href="#id29">Event type</a></h3>
-<p>An event is just a lua table with a predefined metatable that
-contains a __call metamethod. When it is invoked, it loops
+<p>An event is a native object transparently wrapping a lua table,
+and implementing a __call metamethod. When it is invoked, it loops
through the table with next and calls all contained values.
This is intended as an extensible way to add listeners.</p>
<p>This type itself is available in any context, but only the
@@ -1608,9 +1608,15 @@ core context has the actual events defined by C++ code.</p>
<p>Creates a new instance of an event.</p>
</li>
<li><p class="first"><tt class="docutils literal">event[key] = function</tt></p>
-<p>Sets the function as one of the listeners.</p>
+<p>Sets the function as one of the listeners. Assign <em>nil</em> to remove it.</p>
<p><strong>NOTE</strong>: The <tt class="docutils literal">df.NULL</tt> key is reserved for the use by
-the C++ owner of the event, and has some special semantics.</p>
+the C++ owner of the event; it is an error to try setting it.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">#event</tt></p>
+<p>Returns the number of non-nil listeners.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">pairs(event)</tt></p>
+<p>Iterates over all listeners in the table.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">event(args...)</span></tt></p>
<p>Invokes all listeners contained in the event in an arbitrary