This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | Next revision Both sides next revision | ||
|
api:non-standard-lua-libs [2016/06/20 20:38] payonel [Input and Output Facilities] |
api:non-standard-lua-libs [2017/06/11 09:22] payonel |
||
|---|---|---|---|
| Line 66: | Line 66: | ||
| Contains the source of cached libraries in a table, keyed by the library name (as given to `require`), and whose value is the cached library itself. Setting a value to `nil` in this table essentially removes the library from the cache. Some libraries are assumed to remain loaded for the proper execution of the operating system. | Contains the source of cached libraries in a table, keyed by the library name (as given to `require`), and whose value is the cached library itself. Setting a value to `nil` in this table essentially removes the library from the cache. Some libraries are assumed to remain loaded for the proper execution of the operating system. | ||
| - | |||
| - | * ''delayloaded-start'', ''delayloaded-end'' | ||
| - | |||
| - | This is an advanced library loading feature built for memory optimizations in OpenOS. We don't expect users to ever need to use this feature, nor should there be a need to understand it. But it is here because it deserves some documentation. | ||
| - | |||
| - | This specially formatted comment, called a delayload annotation, guides the `package` loader to only partially store a library in memory along with sufficient metadata about which functions have not been loaded. The returned library table uses metatable redirection to lazy-load these not-yet-loaded methods, giving the user the experience that all methods are available form the start. This unusual optimization was done to reduce memory costs on boot of OpenOS. To include a method for delay loading 3 things are required: proper delayload annotation syntax, proper environment boxing, and marking `package.delayed[libname]` to true for the library before loading (i.e. before `require`). | ||
| - | |||
| - | - delayload annotation syntax | ||
| - | |||
| - | This exact text, `--[[@delayloaded-start@]]`, must come after `function` and before the function name. The method must be at least one generation below the library table, e.g. `lib.methodName` or `lib.a.b.methodName`, but not just `methodName`. | ||
| - | |||
| - | `end` must be on a new line, with no text before it, followed by this exact text `--[[@delayloaded-end@]]` followed by a newline. | ||
| - | |||
| - | - delayloaded method environments | ||
| - | |||
| - | Delay loaded methods may expect closure around local identifiers. In order to pass the local environment (and because the oc sandbox does not give sufficient debug hooks), you must return a second table from the library lua file that holds locals needed. For example, if your delay loaded method is using a local function `foobar`, you'll return a env table at the end of your library file, as a second return, of at least `{foobar=foobar}` | ||
| - | |||
| - | - ''package.delayed'' | ||
| - | |||
| - | `package.delayed` is a table whose keys are the library names and values of `true` to indicate to the package loader to attempt to delay load the methods. Note that failed delay load parsing falls back to a normal load of the library. | ||
| - | |||
| - | ```lua | ||
| - | function --[[@delayloaded-start@]] lib.name(...) | ||
| - | body(1,2,3) | ||
| - | end --[[@delayloaded-end@]] | ||
| - | |||
| - | return lib, {body=body} | ||
| - | ``` | ||
| - | |||
| - | ```lua | ||
| - | package.delayed["foobar"] = true | ||
| - | local foobar = require("foobar") | ||
| - | ``` | ||
| - | |||
| String Manipulation | String Manipulation | ||