Differences

This shows you the differences between two versions of the page.

--- api:non-standard-lua-libs [2016/06/20 01:53]
payonel [Modules]
+++ api:non-standard-lua-libs [2016/06/20 20:38]
payonel [Input and Output Facilities]
@@ Line 39: / Line 39: @@
   * ''package.path''
-**It is recommended that users do not change the default package.path and place their custom libraries in /usr/lib/**
+**It is recommended that users do not change the default package.path. Rather they should place their custom libraries in /usr/lib/**
   Defines a list of library search paths that `require` iterates to find libraries. It is a semi-colon delimited list of paths, using '?' as a placeholder for a library name passed to `require`. An example would make this much easier to explain
@@ Line 65: / Line 65: @@
 **It is nonstandard to modify `package.loaded`**
-  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.
+  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")
+```
@@ Line 102: / Line 135: @@
   - **binary mode**
-  Streams given by `io.open(path, "rb")` or `filesystem.open(path)` are in binary mode. `filesystem.open(path, "rb")` also works, but streams returned by `filesystem.open` are **always** in binary mode. `stream:read(1)` in binary mode reads a single byte. Reading a numerical value via `buffered_stream:read("*n")` considers the `string.char()` of each byte (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream)
+  Streams given by `io.open(path, "rb")` or `filesystem.open(path)` are in binary mode. `filesystem.open(path, "rb")` also works, but streams returned by `filesystem.open` are **always** in binary mode. `stream:read(1)` in binary mode reads a single byte. Reading a numerical value via `buffered_stream:read("*n")` reads the data as single-byte characters. (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream)
   - **text mode**
-  Only streams given by `io.open` that specifically do not use "b" in the mode are in text mode. Examples are `io.open(path)` and `io.open(path, "r")`. No type of handle given by `filesystem.open` is a stream in text mode. `stream:read(1)` in text mode reads a single unicode-aware char. This could be a single byte, or even 3 bytes - depending on the text. Reading a numerical value via `buffered_stream:read("*n")` considers the `unicode.char()` of the series of bytes (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream)
+  Only streams given by `io.open` that specifically do not use "b" in the mode are in text mode. Examples are `io.open(path)` and `io.open(path, "r")`. No type of handle given by `filesystem.open` is a stream in text mode. `stream:read(1)` in text mode reads a single unicode-aware char. This could be a single byte, or even 3 bytes - depending on the text. Reading a numerical value via `buffered_stream:read("*n")` reads the data as unicode chars. (buffered streams are returned from `io.open`, and support interpreting numerical values from a stream)
   * `io.open(path, "r")` is equivalent to `io.open(path)`, which opens a file in text read-only mode.