remote

remote is another YALP package that makes it easier to share and pass objects between Pawn and Lua. Complex objects like tables, coroutines, files or other userdata cannot be directly marshalled to native code without risking incorrectly assuming their lifetime. However, if you use the functions in this package, you assume the responsibility to control the lifetime of handled objects.

There are three functions in this package, register, get, and unregister, which help you in sharing Lua objects via Pawn. You can only register a reference type (string, table, full userdata, or coroutine), which will add the object to a special table to keep it alive, and return a pointer to it. You can then pass this pointer around to native functions, and the object it points to will stay alive.

remote.get will, if called from the same Lua instance, retrieve the registered object from its pointer. Optionally, if you pass true as the second argument, it will also unregister the object. You can also unregister the object manually via remote.unregister. Unregistered objects are still accessible, but remote.get on their original pointer will return nil.

If an attempt to retrieve the object is made in another Lua instance, YALP will have to marshal the object to it. Strings are simply copied to the new state (as they are read-only), but other objects may be mutable and need their identities preserved. For this reason, a proxy object is created which translates all operations to the original object. It is possible to call or index the object, and all values passed will be marshalled in the same way as well. If you register load, other Lua instances will basically have full access to the original one.

YALP translates all operations performed on a proxy to the remote Lua instance, via custom metamethods. You can call a proxy, index it, or compare with other objects. However, attempting to call a binary operation on a proxy will only work when the second argument is either a simple value (that can be directly marshalled to the remote Lua instance) or a proxy pointing to the same instance as the first one. If translating the operation would create a new proxy for complex types, its own metatable could handle the remote operation and translate the call back to the original Lua instance and so on. This recursive behavior is only possible for binary operations, so other metamethods are not limited by this.

For checking whether an object is a proxy, you can use remote.isproxy. Other operations, like running a code in the remote Lua instance, must provide the proxy itself. Attempting to perform operations on a dead proxy (connected to a closed Lua state), other than equality, results in an error. remote.isalive can be used to check if a proxy is still alive.