doc/pluto/README

   1 $Id$
   2
   3 PLUTO - Heavy duty persistence for Lua
   4
   5 Pluto is a library which allows users to write arbitrarily large portions
   6 of the "Lua universe" into a flat file, and later read them back into the
   7 same or a different Lua universe. Object references are appropriately
   8 handled, such that the file contains everything needed to recreate the
   9 objects in question.
  10
  11 Pluto has the following major features:
  12 * Can persist any Lua function
  13 * Can persist threads
  14 * Works with any Lua chunkreader/chunkwriter
  15 * Support for "invariant" permanent objects, of all datatypes
  16 * Can invoke metafunctions for custom persistence of tables and userdata
  17
  18 Pluto 2.0 requires Lua 5.1 or later. If you need to use Pluto with Lua
  19 5.0, please use version 1.2 of Pluto.
  20
  21 Pluto may have bugs. Users are advised to define lua_assert in
  22 luaconf.h to something useful when compiling in debug mode, to catch
  23 assertions by Pluto and Lua.
  24
  25 The Pluto library consists of two public functions.
  26
  27 int pluto_persist(lua_State *L, lua_Chunkwriter writer, void *ud)
  28
  29 This function recursively persists the Lua object in stack position 2
  30 and all other objects which are directly or indirectly referenced by
  31 it, except those referenced in the permanent object table. The data
  32 is written using the chunk-writer given, and that writer is passed
  33 the arbitrary pointer value ud.
  34
  35 The Lua stack must contain exactly and only these two items, in order:
  36
  37 1. A table of permanent objects, that should not be persisted. For each
  38 permanent object, the object itself should be the key, and a unique
  39 object of any type should be the value. Likely candidates for this table
  40 include Lua functions (including those in the Lua libraries) that are
  41 loaded at load-time. It must include all non-persistable objects that
  42 are referenced by the object to be persisted. The table is not modified
  43 by the function. Objects in this table are considered "opaque" and are
  44 not examined or descended into. Objects should not appear in the table
  45 multiple times; the result of doing this is undefined (though probably
  46 harmless). NOTE: If you are planning to persist threads, keep in mind
  47 that all yielded threads have coroutine.yield on the tops of their
  48 stacks. Since it's a C function, it should be put here.  For complex
  49 permanents, it may be a good idea to use the __index meta-function of
  50 the permanents table to "search" for permanents.
  51
  52 2. The single object to be persisted. In many cases, this will be the
  53 global table. For more flexibility, however, it may be something like a
  54 table built for the occasion, with various values to keep track of. The
  55 object may not be nil.
  56
  57
  58 int pluto_unpersist(lua_State *L, lua_Chunkreader reader, void *ud)
  59
  60 This function loads in a Lua object and places it on top of the stack. All
  61 objects directly or indirectly referenced by it are also loaded.
  62
  63 The Lua stack must contain, as its top value, a table of permanent
  64 objects. This table should be like the permanent object table used when
  65 persisting, but with the key and value of each pair reversed. These
  66 objects are used as substitutes for those referenced in their positions
  67 when persisting, and under most circumstances should be identical objects
  68 to those referenced in the permanents table used for persisting. It's
  69 okay for multiple keys to refer to the same object.
  70
  71
  72 RUNNING PLUTO FROM LUA:
  73 It is also possible to invoke pluto from a Lua script. The C function
  74 pluto_open() will register pluto.persist and pluto.unpersist, lua functions
  75 which operate on strings. The first takes a permanents table and a root
  76 object, and returns a string; the second takes a permanents table and a
  77 string, and returns the root object.
  78
  79 An error will be raised if pluto.persist is called from a thread which is
  80 itself referenced by the root object.
  81
  82 SPECIAL PERSISTENCE:
  83 Tables and userdata have special persistence semantics. These semantics are
  84 keyed to the value of the object's metatable's __persist member, if any. This
  85 member may be any of the following four values:
  86 1. Boolean "true": The table or userdata is persisted literally; tables are
  87 persisted member-by-member, and userdata are written out as literal data.
  88 2. Boolean "false": An error is returned, indicating that the object cannot
  89 be persisted.
  90 3. A function: This function should take one argument, the object in question,
  91 and return one result, a closure. This "fixup closure", in turn, will be
  92 persisted, and during unpersistence will be called. The closure will be
  93 responsible for recreating the object with the appropriate data, based on
  94 its upvalues.
  95 4. Nil, or no metatable. In the case of tables, the table is literally
  96 persisted. In the case of userdata, an error is returned.
  97
  98 Here's an example of special persistence for a simple 3d vector object:
  99
 100 vec = { x = 2, y = 1, z = 4 }
 101 setmetatable(vec, { __persist = function(oldtbl)
 102         local x = oldtbl.x
 103         local y = oldtbl.y
 104         local z = oldtbl.z
 105         local mt = getmetatable(oldtbl)
 106         return function()
 107                 newtbl = {}
 108                 newtbl.x = x
 109                 newtbl.y = y
 110                 newtbl.z = z
 111                 setmetatable(newtbl, mt)
 112                 return newtbl
 113         end
 114 end })
 115
 116 Note how x, y, z, and the mt are explicitly pulled out of the table. It is
 117 important that the fixup closure returned not reference the original table
 118 directly, as that table would again be persisted as an upvalue, leading to an
 119 infinite loop. Also note that the object's metatable is NOT automatically
 120 persisted; it is necessary for the fixup closure to reset it, if it wants.
 121
 122 LIMITATIONS/TODO:
 123 * Light userdata are persisted literally, as their pointer values. This
 124 may or may not be what you want.
 125 * Closures of C functions may not be persisted. Once it becomes possible
 126 to specify a C function "proto" as a permanent object, this restriction
 127 will be relaxed.
 128
 129 BUGS: None known. Emphasis on the 'known'.