diff options
author | Yaco <franco@reevo.org> | 2021-10-19 20:30:39 -0300 |
---|---|---|
committer | Yaco <franco@reevo.org> | 2021-10-19 20:30:39 -0300 |
commit | 8c201ace3699b4928daf41eb7b4cdcb4565c6f3b (patch) | |
tree | fbd98f026864e9c1919d3ee740b6799ca0c651e2 /www/wiki/extensions/Scribunto/includes/engines/LuaStandalone/protocol.txt | |
parent | e3880a1c86acaa3bbd05786ad2f5c586e6511a58 (diff) |
adds Scribunto
Diffstat (limited to 'www/wiki/extensions/Scribunto/includes/engines/LuaStandalone/protocol.txt')
-rw-r--r-- | www/wiki/extensions/Scribunto/includes/engines/LuaStandalone/protocol.txt | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/www/wiki/extensions/Scribunto/includes/engines/LuaStandalone/protocol.txt b/www/wiki/extensions/Scribunto/includes/engines/LuaStandalone/protocol.txt new file mode 100644 index 00000000..ceb74d35 --- /dev/null +++ b/www/wiki/extensions/Scribunto/includes/engines/LuaStandalone/protocol.txt @@ -0,0 +1,176 @@ +The Lua standalone engine has a message-based protocol for communicating between +PHP and Lua. + +Messages start with a 16 byte header. The first 8 bytes are the body length in +hexadecimal. The second 8 bytes are (length * 2 - 1) also in hexadecimal. + +For messages passed from PHP to Lua, the body is encoded as a Lua expression. +The expression may reference a table in a variable called "chunks", which +contains an array of functions. + +Messages passed from Lua to PHP have their body encoded in PHP serialize() +format, and then "\\", "\r", and "\n" are replaced with "\\\\", "\\r", and +"\\n" to avoid issues with text-mode file handles. They may include instances +of function objects which have an "id" member for passing back to Lua as an +index in the chunk table. + +The expressions encoded into the message bodies are associative arrays. The "op" +member of the array gives the operation to be performed by the message. + +Every request message demands exactly one response message in reply. When a +request message is sent, the responder does not need to send the corresponding +response message as its next message. It may instead send its own request +message. In this way, a stack of pending requests can be accumulated. This +mechanism allows re-entrant and recursive calls. + +All numerically-indexed arrays should start from index 1 unless otherwise +specified. Note that the number of values in an array may not match what Lua's +'#' operator returns if the array contains nils. + +== Request messages sent from PHP to Lua == + +=== loadString === + +Load some executable Lua code (a "chunk") and return the resulting function ID. + +Message parameters: +* op: "loadString" +* text: The string to load +* chunkName: The name of the string, for use in error messages + +On success, the response message is: + +* op: "return" +* nvalues: 1 +* values: An array with a single element with the ID in it + +On failure, the response message is: + +* op: "error" +* value: The error message + +=== call === + +Call a Lua function. + +Message parameters: +* op: "call" +* id: The chunk ID +* nargs: Number of arguments, including nils +* args: The argument array + +On success, the response message is: + +* op: "return" +* nvalues: Number of return values, including nils +* values: All return values as an array + +On failure, the response message is: + +* op: "error" +* value: The value given to error(), usually an error message +* trace: A table giving a backtrace of the stack as it was when error() was + called, in a similar format to the one used by debug.getinfo(). Element 1 of + the table is the function that called error(), element 2 is the function that + called that, and so on. + +=== registerLibrary === + +Register a set of functions in the sandbox environment. + +Message parameters: +* op: "registerLibrary" +* name: The global variable name to register. May contain "." characters to + specify a global variable subtable. +* functions: An associative array mapping function name to ID + +On success, the response message is: + +* op: "return" +* nvalues: 0 +* values: An empty array + +On failure the response message is: + +* op: "error" +* value: The error message + +=== getStatus === + +Get status information about the Lua process. + +Message parameters: +* op: "getStatus" + +On success, the response message is: + +* op: "return" +* nvalues: 1 +* values: An array with a single element, which is an associative array mapping + status key to value. The status keys are: +** pid: The process identifier +** time: The amount of user and system time spent by the process, measured in clock ticks +** vsize: The virtual memory size in bytes +** rss: The resident set size in bytes + +On failure, the response message is: + +* op: "return" +* nvalues: 0 +* values: An empty array + +=== cleanupChunks === + +Tell Lua to release any chunks no longer referenced by PHP. + +Message parameters: +* op: "cleanupChunks" +* ids: Table with keys being the chunk IDs still referenced by PHP, and non-falsey values + +The response message is: + +* op: "return" +* nvalues: 0 +* values: An empty array + +=== quit === + +Request graceful shutdown. + +Message parameters: +* op: "quit" + +No return message will be sent. + +=== testquit === + +Request non-graceful shutdown, for testing. + +Message parameters: +* op: "testquit" + +No return message will be sent. + +== Request messages sent from Lua to PHP == + +=== call === + +Call a PHP function. + +Message parameters: +* op: "call" +* id: The function ID given by registerLibrary +* nargs: Number of arguments, including nils +* args: An array giving the function arguments + +On success, the response message is: + +* op: "return" +* nvalues: Number of return values, including nils +* values: All return values as an array + +On failure the response message is: + +* op: "error" +* value: The error message + |