Replaced __lanesignore with __lanesconvert

4 files changed, 121 insertions, 64 deletions

diff --git a/docs/index.html b/docs/index.html
index 60f4970..24c7c52 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -546,7 +546,7 @@
                         </td>
                         <td />
                         <td>
-                                root level names, <tt>print</tt>, <tt>assert</tt>, <tt>unpack</tt> etc.
+                                <tt>_G</tt> namespace (the default function environment): <tt>print</tt>, <tt>assert</tt>, <tt>dofile</tt>, etc.
                         </td>
                 </tr>
                 <tr>
@@ -1150,13 +1150,13 @@
 <h2 id="lindas">Lindas</h2>
 
 <p>
-        Communications between lanes is completely detached from the lane handles themselves. By itself, a lane can only provide return values once it's finished, or throw an error.
+        Communications between lanes is completely detached from the lane handles themselves. By itself, a lane can only provide return values once it is finished, or throw an error.
         Needs to communicate during runtime are handled by <a href="http://en.wikipedia.org/wiki/Linda_%28coordination_language%29" target="_blank">Linda objects</a>, which are
         <a href="#deep_userdata">deep userdata</a> instances. They can be provided to a lane as startup parameters, upvalues or in some other Linda's message.
 </p>
 
 <p>
-        Access to a Linda object means a lane can read or write to any of its data slots. Multiple lanes can be accessing the same Linda in parallel. No application level locking is required; each Linda operation is atomic.
+        Access to a Linda object means a lane can read or write to any of its data slots. Multiple lanes can be accessing the same Linda simultaneously. Seen from Lua, no application level locking is required; each Linda operation is atomic.
 </p>
 
 <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
@@ -1212,35 +1212,53 @@
 
 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
         h = lanes.linda([opt_name, [opt_group]])
+</pre></td></tr></table>
 
-        true|lanes.cancel_error = h:send([timeout_secs,] key, ...)
+<p>
+        Converting the Linda to a string will yield the provided name prefixed by <tt>"Linda: "</tt>.<br/>
+        If <tt>opt_name</tt> is omitted, it will evaluate to an hexadecimal number uniquely representing that Linda when the Linda is converted to a string. The value is the same as returned by <tt>linda:deep()</tt>.<br/>
+        If <tt>opt_name</tt> is <tt>"auto"</tt>, Lanes will try to construct a name from the source location that called <tt>lanes.linda()</tt>. If that fails, the Linda name will be <tt>"&lt;unresolved&gt;"</tt>.
+</p>
 
-        key, val = h:receive([timeout_secs,] key [, key...])
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+        true|lanes.cancel_error = h:limit(key, n_uint)
+</pre></td></tr></table>
 
-        key, val [, val...] = h:receive(timeout, h.batched, key, n_uint_min[, n_uint_max])
+<p>
+        By default, queue sizes are unlimited but limits can be enforced using the <tt>limit()</tt> method. This can be useful to balance execution speeds in a producer/consumer scenario. <tt>nil</tt> removes the limit.<br/>
+        A limit of 0 is allowed to block everything.<br/>
+        If the key was full but the limit change added some room, <tt>limit()</tt> returns <tt>true</tt> and the Linda is signalled so that <tt>send()</tt>-blocked threads are awakened.<br/>
+</p>
 
-        true|lanes.cancel_error = h:limit(key, n_uint)
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+        true|lanes.cancel_error = h:send([timeout_secs,] key, ...)
 </pre></td></tr></table>
 
 <p>
-        Converting the Linda to a string will yield the provided name prefixed by <tt>"Linda: "</tt>.<br/>
-        If <tt>opt_name</tt> is omitted, it will evaluate to an hexadecimal number uniquely representing that Linda when the Linda is converted to a string. The value is the same as returned by <tt>linda:deep()</tt>.<br/>
-        If <tt>opt_name</tt> is <tt>"auto"</tt>, Lanes will try to construct a name from the source location that called <tt>lanes.linda()</tt>. If that fails, the Linda name will be <tt>"&lt;unresolved&gt;"</tt>.
+        Timeouts are given in seconds (&gt= 0, millisecond accuracy) or <tt>nil</tt>. Timeout can be omitted only if the first key is not a number (then it is equivalent to an infinite duration).<br/>
+        Each key acts as a FIFO queue. There is no limit to the number of keys a Linda may contain. Different Lindas can have identical keys, which are totally unrelated.
 </p>
 <p>
-        Timeouts are given in seconds (&gt= 0, millisecond accuracy) or <tt>nil</tt>. Timeout can be omitted only if the first key is not a number (then it's equivalent to an infinite duration).
+        If no data is provided after the key, <tt>send()</tt> raises an error.<br/>
+        Also, if <tt>linda.null</tt> or <tt>lanes.null</tt> is sent as data in a Linda, it will be read as a <tt>nil</tt>.<br/>
+        <tt>send()</tt> returns <tt>true</tt> if the sending succeeded, and <tt>false</tt> if the queue limit was met, and the queue did not empty enough during the given timeout.<br/>
+        <tt>send()</tt> returns <tt>lanes.cancel_error</tt> if interrupted by a soft cancel request.<br/>
 </p>
 
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+        key, val = h:receive([timeout_secs,] key [, key...])
+
+        key, val [, val...] = h:receive(timeout, h.batched, key, n_uint_min[, n_uint_max])
+</pre></td></tr></table>
+
+
 <p>
         The <tt>send()</tt> and <tt>receive()</tt> methods use Linda keys as FIFO stacks (first in, first out).<br/>
-        By default, stack sizes are unlimited but limits can be enforced using the <tt>limit()</tt> method. This can be useful to balance execution speeds in a producer/consumer scenario. <tt>nil</tt> removes the limit.<br/>
-        A limit of 0 is allowed to block everything.<br/>
-        If the key was full but the limit change added some room, <tt>limit()</tt> returns <tt>true</tt> and the Linda is signalled so that <tt>send()</tt>-blocked threads are awakened.<br/>
         In batched mode, <tt>linda:receive()</tt> will raise an error if <tt>min_count < 1</tt> or <tt>max_count < min_count</tt>.
 </p>
 
 <p>
-        Note that any number of lanes can be reading or writing a Linda. There can be many producers, and many consumers. It's up to you.
+        Note that any number of lanes can be reading or writing a Linda. There can be many producers, and many consumers. It is up to you.
 </p>
 
 <p>
@@ -1248,16 +1266,6 @@
 </p>
 
 <p>
-        <tt>send()</tt> returns <tt>true</tt> if the sending succeeded, and <tt>false</tt> if the queue limit was met, and the queue did not empty enough during the given timeout.
-        <br/>
-        <tt>send()</tt> returns <tt>lanes.cancel_error</tt> if interrupted by a soft cancel request.
-        <br/>
-        If no data is provided after the key, <tt>send()</tt> raises an error.
-        <br/>
-        Also, if <tt>linda.null</tt> or <tt>lanes.null</tt> is sent as data in a Linda, it will be read as a <tt>nil</tt>.
-</p>
-
-<p>
         Equally, <tt>receive()</tt> returns a key and the value extracted from it. Note that <tt>nil</tt>s can be sent and received; the <tt>key</tt> value will tell it apart from a timeout.<br/>
         <tt>receive()</tt> returns <tt>nil, lanes.cancel_error</tt> if interrupted by a hard cancel request.<br/>
         <tt>receive()</tt> returns <tt>nil, "timeout"</tt> if nothing was available.
@@ -1558,14 +1566,22 @@ On the other side, you need to use a common Linda for waiting for multiple keys.
                         to the global table in the destination state. Note that this also applies when Lanes is built for Lua 5.1, as it doesn't hurt.
                 </li>
                 <li>
-                        Full userdata can be passed only if it's prepared using the <a href="#deep_userdata">deep userdata</a> system, which handles its lifespan management
+                        Full userdata can be passed only if it is prepared using the <a href="#deep_userdata">deep userdata</a> system, which handles its lifespan management
                         <ul>
                                 <li>In particular, lane handles cannot be passed between lanes.</li>
                                 <li>Lanes can either throw an error or attempt a <a href="#demote_full_userdata">light userdata demotion</a>.</li>
                         </ul>
                 </li>
                 <li>Coroutines cannot be passed. A coroutine's Lua state is tied to the Lua state that created it, and there is no way the mixed C/Lua stack of a coroutine can be transfered from one Lua state to another.</li>
-                <li>If the metatable contains <tt>__lanesignore</tt>, the object is skipped and <tt>nil</tt> is transfered instead.</li>
+                <li>
+                        If the metatable contains <tt>__lanesconvert</tt>, the object is converted as follows depending on the value:
+                        <ul>
+                                <li><tt>lanes.null</tt>: The value is converted to <tt>nil</tt>.</li>
+                                <li><tt>"decay"</tt>: The value is converted to a light userdata obtained from <tt>lua_topointer()</tt>.</li>
+                                <li>A function: The function is called as <tt>o:__lanesconvert(string)</tt>, where the argument is either <tt>"keeper"</tt> or <tt>"regular"</tt>, depending on the type of destination. Its (single) return value is the result of the conversion.</li>
+                                <li>Any other value raises an error.</li>
+                        </ul>
+                </li>
         </ul>
 </p>
 
@@ -1573,26 +1589,7 @@ On the other side, you need to use a common Linda for waiting for multiple keys.
 <h3 id="function_notes">Notes about passing C functions</h3>
 
 <p>
-        Originally, a C function was copied from one Lua state to another as follows:
-</p>
-
-<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
-        // expects a C function on top of the source Lua stack
-        copy_func(lua_State *dest, lua_State* source)
-        {
-                // extract C function pointer from source
-                lua_CFunction func = lua_tocfunction(source, -1);
-                // transfer upvalues
-                int nup = transfer_upvalues(dest, source);
-                // dest Lua stack contains a copy of all upvalues
-                lua_pushcfunction(dest, func, nup);
-        }
-</pre></td></tr></table>
-
-<p>
-        This has the main drawback of not being LuaJIT-compatible, because some functions registered by LuaJIT are not regular C functions, but specially optimized implementations. As a result, <tt>lua_tocfunction()</tt> returns <tt>nullptr</tt> for them.
-        <br/>
-        Therefore, Lanes no longer transfers functions that way. Instead, functions are transfered as follows (more or less):
+        Functions are transfered as follows (more or less):
 </p>
 
 <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
diff --git a/src/intercopycontext.cpp b/src/intercopycontext.cpp
index c7fcf14..a5fd400 100644
--- a/src/intercopycontext.cpp
+++ b/src/intercopycontext.cpp
@@ -532,6 +532,76 @@ void InterCopyContext::inter_copy_keyvaluepair() const
 
 // #################################################################################################
 
+LuaType InterCopyContext::processConversion() const
+{
+    static constexpr int kPODmask = (1 << LUA_TNIL) | (1 << LUA_TBOOLEAN) | (1 << LUA_TLIGHTUSERDATA) | (1 << LUA_TNUMBER) | (1 << LUA_TSTRING);
+
+    LuaType _val_type{ luaG_type(L1, L1_i) };
+
+    STACK_CHECK_START_REL(L1, 0);
+
+    // it's a POD: nothing to do
+    if (((1 << static_cast<int>(_val_type)) & kPODmask) != 0) {
+        return _val_type;
+    }
+
+    // no metatable: nothing to do
+    if (!lua_getmetatable(L1, L1_i)) {                                                             // L1: ...
+        STACK_CHECK(L1, 0);
+        return _val_type;
+    }
+    // we have a metatable                                                                         // L1: ... mt
+    static constexpr std::string_view kConvertField{ "__lanesconvert" };
+    LuaType const _converterType{ luaG_getfield(L1, -1, kConvertField) };                          // L1: ... mt kConvertField
+    switch (_converterType) {
+    case LuaType::NIL:
+        // no __lanesconvert, nothing to do
+        lua_pop(L1, 2);                                                                            // L1: ...
+        break;
+
+    case LuaType::LIGHTUSERDATA:
+        if (kNilSentinel.equals(L1, -1)) {
+            DEBUGSPEW_CODE(DebugSpew(U) << "converted " << luaG_typename(L1, _val_type) << " to nil" << std::endl);
+            lua_replace(L1, L1_i);                                                                 // L1: ... mt
+            lua_pop(L1, 1);                                                                        // L1: ...
+            _val_type = _converterType;
+        } else {
+            raise_luaL_error(getErrL(), "Invalid %s type %s", kConvertField.data(), luaG_typename(L1, _converterType).data());
+        }
+        break;
+
+    case LuaType::STRING:
+        // kConvertField == "decay" -> replace source value with it's pointer
+        if (std::string_view const _mode{ luaG_tostring(L1, -1) }; _mode == "decay") {
+            lua_pop(L1, 1);                                                                        // L1: ... mt
+            lua_pushlightuserdata(L1, const_cast<void*>(lua_topointer(L1, L1_i)));                 // L1: ... mt decayed
+            lua_replace(L1, L1_i);                                                                 // L1: ... mt
+            lua_pop(L1, 1);                                                                        // L1: ...
+            _val_type = LuaType::LIGHTUSERDATA;
+        } else {
+            raise_luaL_error(getErrL(), "Invalid %s mode '%s'", kConvertField.data(), _mode.data());
+        }
+        break;
+
+    case LuaType::FUNCTION:
+        lua_pushvalue(L1, L1_i);                                                                   // L1: ... mt kConvertField val
+        std::ignore = luaG_pushstring(L1, mode == LookupMode::ToKeeper ? "keeper" : "regular");    // L1: ... mt kConvertField val string
+        lua_call(L1, 2, 1); // val:kConvertField(str) -> result                                    // L1: ... mt kConvertField converted
+        lua_replace(L1, L1_i);                                                                     // L1: ... mt
+        lua_pop(L1, 1);                                                                            // L1: ... mt
+        _val_type =  luaG_type(L1, L1_i);
+        break;
+
+    default:
+        raise_luaL_error(getErrL(), "Invalid %s type %s", kConvertField.data(), luaG_typename(L1, _converterType).data());
+    }
+    STACK_CHECK(L1, 0);
+    LUA_ASSERT(getErrL(), luaG_type(L1, L1_i) == _val_type);
+    return _val_type;
+}
+
+// #################################################################################################
+
 [[nodiscard]] bool InterCopyContext::push_cached_metatable() const
 {
     STACK_CHECK_START_REL(L1, 0);
@@ -1085,21 +1155,10 @@ namespace {
     DEBUGSPEW_CODE(DebugSpew(U) << "inter_copy_one()" << std::endl);
     DEBUGSPEW_CODE(DebugSpewIndentScope _scope{ U });
 
-    LuaType _val_type{ luaG_type(L1, L1_i) };
-    DEBUGSPEW_CODE(DebugSpew(U) << local::sLuaTypeNames[static_cast<int>(_val_type)] << " " << local::sValueTypeNames[static_cast<int>(vt)] << ": ");
-
-    // Non-POD can be skipped if its metatable contains { __lanesignore = true }
-    if (((1 << static_cast<int>(_val_type)) & kPODmask) == 0) {
-        if (lua_getmetatable(L1, L1_i)) {                                                          // L1: ... mt
-            LuaType const _type{ luaG_getfield(L1, -1, "__lanesignore") };                         // L1: ... mt ignore?
-            if (_type == LuaType::BOOLEAN && lua_toboolean(L1, -1)) {
-                DEBUGSPEW_CODE(DebugSpew(U) << "__lanesignore -> LUA_TNIL" << std::endl);
-                _val_type = LuaType::NIL;
-            }
-            lua_pop(L1, 2);                                                                        // L1: ...
-        }
-    }
+    // replace the value at L1_i with the result of a conversion if required
+    LuaType const _val_type{ processConversion() };
     STACK_CHECK(L1, 0);
+    DEBUGSPEW_CODE(DebugSpew(U) << local::sLuaTypeNames[static_cast<int>(_val_type)] << " " << local::sValueTypeNames[static_cast<int>(vt)] << ": ");
 
     // Lets push nil to L2 if the object should be ignored
     bool _ret{ true };
diff --git a/src/intercopycontext.h b/src/intercopycontext.h
index ffa825f..459551e 100644
--- a/src/intercopycontext.h
+++ b/src/intercopycontext.h
@@ -38,10 +38,11 @@ class InterCopyContext
     char const* name; // that one can change when we reuse the context
 
     private:
+    [[nodiscard]] std::string_view findLookupName() const;
     // when mode == LookupMode::FromKeeper, L1 is a keeper state and L2 is not, therefore L2 is the state where we want to raise the error
     // whon mode != LookupMode::FromKeeper, L1 is not a keeper state, therefore L1 is the state where we want to raise the error
     lua_State* getErrL() const { return (mode == LookupMode::FromKeeper) ? L2 : L1; }
-    [[nodiscard]] std::string_view findLookupName() const;
+    [[nodiscard]] LuaType processConversion() const;
 
     // for use in copy_cached_func
     void copy_func() const;
diff --git a/tests/basic.lua b/tests/basic.lua
index 20865cf..28f0334 100644
--- a/tests/basic.lua
+++ b/tests/basic.lua
@@ -226,7 +226,7 @@ local chunk= function(linda)
     k,v=receive(); WR("chunk ", v.." received (expecting 1)\n"); assert(v==1)
     k,v=receive(); WR("chunk ", v.." received (expecting 2)\n"); assert(v==2)
     k,v=receive(); WR("chunk ", v.." received  (expecting 3)\n"); assert(v==3)
-    k,v=receive(); WR("chunk ", tostring(v).." received  (expecting nil from __lanesignore)\n"); assert(v==nil) -- a table with __lanesignore was sent
+    k,v=receive(); WR("chunk ", tostring(v).." received  (expecting nil from __lanesconvert)\n"); assert(v==nil, "table with __lanesconvert==lanes.null should be received as nil, got " .. tostring(v)) -- a table with __lanesconvert was sent
     k,v=receive(); WR("chunk ", tostring(v).." received (expecting nil)\n"); assert(v==nil)
 
     send(4,5,6);              WR("chunk ", "4,5,6 sent\n")
@@ -277,7 +277,7 @@ local comms_lane = lanes_gen("io", {gc_cb = gc_cb, name = "auto"}, chunk)(linda)
 SEND(1);  WR("main ", "1 sent\n")
 SEND(2);  WR("main ", "2 sent\n")
 SEND(3);  WR("main ", "3 sent\n")
-SEND(setmetatable({"should be ignored"},{__lanesignore=true})); WR("main ", "__lanesignore table sent\n")
+SEND(setmetatable({"should be ignored"},{__lanesconvert=lanes.null})); WR("main ", "__lanesconvert table sent\n")
 for i=1,40 do
     WR "."
     SLEEP(0.0001)