Deep userdata support improvements

* bumped version to 3.9.0
* keepers now require "package", receive package.path & package.cpath,
and call on_state_create() if it is a C function
* changed the deep public API (improved deep idfunc signature, renamed
luaG_deep_userdata to luaG_newdeepuserdata)
* if an error occurs while copying a deep userdata, don't raise inside
the keeper state
* fixed situations where raised errors could lead to memory leaks (deep
gc)

1 files changed, 22 insertions, 10 deletions

diff --git a/index.html b/index.html
index 2468ad8..051f9d0 100644
--- a/index.html
+++ b/index.html
@@ -70,7 +70,7 @@
                         </p>
 
                         <p>
-                                This document was revised on 13-Feb-14, and applies to version <tt>3.8.5</tt>.
+                                This document was revised on 17-Feb-14, and applies to version <tt>3.9.0</tt>.
                         </p>
                 </font>
         </center>
@@ -355,7 +355,9 @@
                                 function/<tt>nil</tt>
                         </td>
                         <td>
-                                If provided, will be called in every created Lua state (keepers and lanes) right after initializing the base libraries.
+                                If provided, will be called in every created Lua state right after initializing the base libraries.
+                                <br/>
+                                Keeper states will call it as well, but only if it is a C function (keeper states are not able to execute any user Lua code).
                                 <br/>
                                 Typical usage is twofold:
                                 <ul>
@@ -1493,18 +1495,18 @@ events to a common Linda, but... :).</font>
 <ol>
         <li>
                 Provide an <i>identity function</i> for your userdata, in C. This function is used for creation and deletion of your deep userdata (the shared resource), and for making metatables for the state-specific proxies for accessing it. The prototype is
-                <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>    void idfunc( lua_State *L, char const * const which);</pre></td></tr></table>
-                <tt>which</tt> can be one of:
+                <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>    void* idfunc( lua_State* L, enum eDeepOp op_);</pre></td></tr></table>
+                <tt>op_</tt> can be one of:
                 <ul>
-                        <li><tt>"new"</tt>: requests the creation of a new object, whose pointer is pushed on the stack as a light userdata.</li>
-                        <li><tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>
-                        <li><tt>"metatable"</tt>: should build a metatable for the object. Don't cache the metatable yourself, Lanes takes care of it ("metatable" should only be invoked once).</li>
-                        <li><tt>"module"</tt>: is the name of the module that exports the idfunc, to be pushed on the stack as a string. It is necessary so that Lanes can require it in any Lane and keeper state that receives a userdata. This is to prevent crashes in situations where the module could be unloaded while the idfunc pointer is still held.</li>
+                        <li><tt>eDO_new</tt>: requests the creation of a new object, whose pointer is returned.</li>
+                        <li><tt>eDO_delete</tt>: receives this same pointer on the stack as a light userdata, and should cleanup the object.</li>
+                        <li><tt>eDO_metatable</tt>: should build a metatable for the object. Don't cache the metatable yourself, Lanes takes care of it (<tt>eDO_metatable</tt> should only be invoked once per state).</li>
+                        <li><tt>eDO_module</tt>: requests the name of the module that exports the idfunc, to be returned. It is necessary so that Lanes can require it in any lane state that receives a userdata. This is to prevent crashes in situations where the module could be unloaded while the idfunc pointer is still held.</li>
                 </ul>
                 Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.
         </li>
         <li>Include <tt>"deep.h"</tt> and link against Lanes.
-        <li>Instanciate your userdata using <tt>luaG_deep_userdata()</tt>, instead of the regular <tt>lua_newuserdata()</tt>. Given an <tt>idfunc</tt>, it sets up the support structures and returns a state-specific proxy userdata for accessing your data. This proxy can also be copied over to other lanes.</li>
+        <li>Instanciate your userdata using <tt>luaG_newdeepuserdata()</tt>, instead of the regular <tt>lua_newuserdata()</tt>. Given an <tt>idfunc</tt>, it sets up the support structures and returns a state-specific proxy userdata for accessing your data. This proxy can also be copied over to other lanes.</li>
         <li>Accessing the deep userdata from your C code, use <tt>luaG_todeep()</tt> instead of the regular <tt>lua_touserdata()</tt>.</li>
 </ol>
 
@@ -1513,7 +1515,17 @@ events to a common Linda, but... :).</font>
 </p>
 
 <p>
-        <b>NOTE</b>: The lifespan of deep userdata may exceed that of the Lua state that created it. The allocation of the data storage should not be tied to the Lua state used. In other words, use <tt>malloc</tt>/<tt>free</tt> or similar memory handling mechanism.
+        Deep userdata in transit inside keeper states (sent in a linda but not yet consumed) don't call <tt>idfunc(eDO_delete)</tt> and aren't considered by reference counting. The rationale is the following:
+        <br/>
+        If some non-keeper state holds a deep userdata for some deep object, then even if the keeper collects its own deep userdata, it shouldn't be cleaned up since the refcount is not 0.
+        <br/>
+        OTOH, if a keeper state holds the last deep userdata for some deep object, then no lane can do actual work with it. But as it happens, deep userdata are only copied to and from keeper states. Most notably, the object's <tt>idfunc()</tt> is never called from a keeper state.
+        <br/>
+        Therefore, Lanes can just call <tt>idfunc(eDO_delete)</tt> when the last non-keeper-held deep userdata is collected, as long as it doens't do the same in a keeper state after that, since any remaining deep userdata in keeper states now hold stale pointers.
+</p>
+
+<p>
+        <b>NOTE</b>: The lifespan of deep userdata may exceed that of the Lua state that created it. The allocation of the data storage should not be tied to the Lua state used. In other words, use <tt>malloc()</tt>/<tt>free()</tt> or similar memory handling mechanism.
 </p>