doc/manual/springs-ref.tex

   1 \section{{\tt springs}: separate universes for Lua}
   2
   3 \subsection{Origins and purpose}
   4 Springs (Serialization through Pluto for RINGS) is an extension of Lua Rings and
   5 Pluto: Lua Rings allow to create new Lua states from within Lua, but offer
   6 limited communication between them: a master universe can only send instruction
   7 to a slave universe through a ``{\tt dostring}'', and the slave universe can
   8 only send back strings, integers and booleans as results. Since Pluto allows to
   9 serialize pretty much any Lua value as a string, it's used to create powerful
  10 bidirectional communications between universes.
  11
  12 Springs is used internally by metalua to prevent different files' compile time
  13 actions to interfere with each other: each file is compiled on a fresh clean
  14 single-use slate.
  15
  16 The underlying projects can be found on the web:
  17 \begin{itemize}
  18 \item \verb|<http://www.keplerproject.org/rings/>|
  19 \item \verb|<http://luaforge.net/projects/pluto/>|
  20 \end{itemize}
  21 Notice however that the Pluto version used in metalua is significantly patched
  22 and debugged by Ivko Stanilov.
  23
  24 \subsection{API}
  25 Go to Lua Rings web site for a reference on its original API. This API is
  26 extended by spring with:
  27 \begin{itemize}
  28 \item function {\tt springs.new()} which creates a new universe ready for Pluto
  29   communication;
  30 \item ({\tt:dostring()} works as usual)
  31 \item {\tt :pcall(f, arg1, ..., argn)} works as standard function pcall(),
  32   except that execution occurs in the sub-state. Arguments are passed and
  33   results are returned transparently acrosse universes. Moreover, 'f' can also
  34   be a string, rather than a function. If it's a string, it must eval to a
  35   function in the substate's context. This allows to pass standard functions
  36   easily. For instance:\\
  37   \verb|r:pcall('table.concat', {'a', 'b', 'c'}, ',')|
  38 \item {\tt :call()} is similar to :pcall(), except that in case of error, it
  39   actually throws the error in the senders universe's context. Therefore, it
  40   doesn't return a success status as does pcall(). For instance: \\
  41   \verb|assert('xxx' == r:call('string.rep', 'x', 3))|
  42 \end{itemize}