API for functions to manipulate global state.

5 files changed, 98 insertions, 32 deletions

diff --git a/lbuffer.c b/lbuffer.c
index d5aa8c98..fc20ce1a 100644
--- a/lbuffer.c
+++ b/lbuffer.c
@@ -1,5 +1,5 @@
 /*
-** $Id: lbuffer.c,v 1.1 1997/12/23 19:24:36 roberto Exp roberto $
+** $Id: lbuffer.c,v 1.2 1998/03/06 16:54:42 roberto Exp roberto $
 ** Auxiliar functions for building Lua libraries
 ** See Copyright Notice in lua.h
 */
@@ -22,7 +22,7 @@
 
 static void Openspace (int size)
 {
-  LState *l = L;  /* to optimize */
+  lua_State *l = L;  /* to optimize */
   int base = l->Mbuffbase-l->Mbuffer;
   l->Mbuffsize *= 2;
   if (l->Mbuffnext+size > l->Mbuffsize)  /* still not big enough? */
diff --git a/lstate.c b/lstate.c
index c1a1b43d..434bd0bd 100644
--- a/lstate.c
+++ b/lstate.c
@@ -1,5 +1,5 @@
 /*
-** $Id: lstate.c,v 1.4 1997/12/11 14:48:46 roberto Exp roberto $
+** $Id: lstate.c,v 1.5 1997/12/17 20:48:58 roberto Exp roberto $
 ** Global State
 ** See Copyright Notice in lua.h
 */
@@ -17,13 +17,13 @@
 #include "ltm.h"
 
 
-LState *lua_state = NULL;
+lua_State *lua_state = NULL;
 
 
 void lua_open (void)
 {
   if (lua_state) return;
-  lua_state = luaM_new(LState);
+  lua_state = luaM_new(lua_State);
   L->numCblocks = 0;
   L->Cstack.base = 0;
   L->Cstack.lua2C = 0;
@@ -76,3 +76,11 @@ void lua_close (void)
   printf("total de memoria: %ld\n", totalmem);
 #endif
 }
+
+
+lua_State *lua_setstate (lua_State *st) {
+  lua_State *old = lua_state;
+  lua_state = st;
+  return old;
+}
+
diff --git a/lstate.h b/lstate.h
index 21cbef59..6692e097 100644
--- a/lstate.h
+++ b/lstate.h
@@ -1,5 +1,5 @@
 /*
-** $Id: lstate.h,v 1.7 1998/01/09 14:57:43 roberto Exp $
+** $Id: lstate.h,v 1.8 1998/05/27 13:03:40 roberto Exp roberto $
 ** Global State
 ** See Copyright Notice in lua.h
 */
@@ -8,6 +8,7 @@
 #define lstate_h
 
 #include "lobject.h"
+#include "lua.h"
 
 
 #define MAX_C_BLOCKS 10
@@ -44,10 +45,18 @@ struct ref {
 };
 
 
-typedef struct LState {
+struct lua_State {
+  /* trhead-specific state */
   struct Stack stack;  /* Lua stack */
   struct C_Lua_Stack Cstack;  /* C2lua struct */
   void *errorJmp;  /* current error recover point */
+  char *Mbuffer;  /* global buffer */
+  char *Mbuffbase;  /* current first position of Mbuffer */
+  int Mbuffsize;  /* size of Mbuffer */
+  int Mbuffnext;  /* next position to fill in Mbuffer */
+  struct C_Lua_Stack Cblocks[MAX_C_BLOCKS];
+  int numCblocks;  /* number of nested Cblocks */
+  /* global state */
   TObject errorim;  /* error tag method */
   GCnode rootproto;  /* list of all prototypes */
   GCnode rootcl;  /* list of all closures */
@@ -61,16 +70,10 @@ typedef struct LState {
   int refSize;  /* size of refArray */
   unsigned long GCthreshold;
   unsigned long nblocks;  /* number of 'blocks' currently allocated */
-  char *Mbuffer;  /* global buffer */
-  char *Mbuffbase;  /* current first position of Mbuffer */
-  int Mbuffsize;  /* size of Mbuffer */
-  int Mbuffnext;  /* next position to fill in Mbuffer */
-  struct C_Lua_Stack Cblocks[MAX_C_BLOCKS];
-  int numCblocks;  /* number of nested Cblocks */
-} LState;
+};
 
 
-extern LState *lua_state;
+extern lua_State *lua_state;
 
 
 #define L       lua_state
diff --git a/lua.h b/lua.h
index 5e513a94..b200c20b 100644
--- a/lua.h
+++ b/lua.h
@@ -1,5 +1,5 @@
 /*
-** $Id: lua.h,v 1.17 1998/03/06 18:47:42 roberto Exp roberto $
+** $Id: lua.h,v 1.18 1998/05/18 22:26:03 roberto Exp roberto $
 ** Lua - An Extensible Extension Language
 ** TeCGraf: Grupo de Tecnologia em Computacao Grafica, PUC-Rio, Brazil
 ** e-mail: lua@tecgraf.puc-rio.br
@@ -55,9 +55,12 @@
 typedef void (*lua_CFunction) (void);
 typedef unsigned int lua_Object;
 
+typedef struct lua_State lua_State;
+extern lua_State *lua_state;
 
 void           lua_open                 (void);
 void           lua_close                (void);
+lua_State      *lua_setstate            (lua_State *st);
 
 lua_Object     lua_settagmethod (int tag, char *event); /* In: new method */
 lua_Object     lua_gettagmethod (int tag, char *event);
@@ -70,6 +73,8 @@ void           lua_settag		(int tag); /* In: object */
 void           lua_error                (char *s);
 int            lua_dofile               (char *filename); /* Out: returns */
 int            lua_dostring             (char *string); /* Out: returns */
+int            lua_dobuffer             (char *buff, int size);
+                                          /* Out: returns */
 int            lua_callfunction         (lua_Object f);
                                           /* In: parameters; Out: returns */
 
diff --git a/manual.tex b/manual.tex
index 041590c4..27f3df12 100644
--- a/manual.tex
+++ b/manual.tex
@@ -1,4 +1,4 @@
-% $Id: manual.tex,v 1.10 1998/05/20 22:21:35 roberto Exp roberto $
+% $Id: manual.tex,v 1.11 1998/05/27 19:09:39 roberto Exp roberto $
 
 \documentstyle[fullpage,11pt,bnf]{article}
 
@@ -38,7 +38,7 @@ Waldemar Celes
 \tecgraf\ --- Computer Science Department --- PUC-Rio
 }
 
-\date{\small \verb$Date: 1998/05/20 22:21:35 $}
+\date{\small \verb$Date: 1998/05/27 19:09:39 $}
 
 \maketitle
 
@@ -1291,6 +1291,7 @@ the set of C functions available to the host program to communicate
 with the Lua library.
 The API functions can be classified in the following categories:
 \begin{enumerate}
+\item managing states;
 \item exchanging values between C and Lua;
 \item executing Lua code;
 \item manipulating (reading and writing) Lua objects;
@@ -1301,30 +1302,76 @@ The API functions can be classified in the following categories:
 All API functions and related types and constants
 are declared in the header file \verb|lua.h|.
 
+\subsection{Managing States}
+The whole state of the Lua interpreter
+(global variables, stack, tag methods, etc)
+is stored in a dynamic structure pointed by\Deffunc{lua_state}
+\begin{verbatim}
+typedef struct lua_State lua_State;
+extern lua_State *lua_state;
+\end{verbatim}
+
 Before calling any API function,
-the library must be initalizated.
-This is done by calling:\Deffunc{lua_open}
+this state must be initialized.
+This is done by calling\Deffunc{lua_open}
 \begin{verbatim}
 void           lua_open                 (void);
 \end{verbatim}
 This function allocates and initializes some internal structures,
 and defines all pre-defined functions of Lua.
-If the library is already opened,
-this function has no effect.
+If \verb|lua_state| is already different from \verb|NULL|,
+this function has no effect;
+therefore, it is safe to call this function multiple times.
 All standard libraries call \verb|lua_open| when they are opened.
 
-If necessary, the library may be closed:\Deffunc{lua_close}
+Function \verb|lua_setstate| is used to change the current state
+of Lua:\Deffunc{lua_setstate}
+\begin{verbatim}
+lua_State      *lua_setstate            (lua_State *st);
+\end{verbatim}
+It sets \verb|lua_state| to \verb|st| and returns the old state.
+
+Multiple, independent, states may be created.
+For that, you must set \verb|lua_state| back to \verb|NULL| before
+calling \verb|lua_open|.
+An easy way to do that is defining an auxiliary function:
+\begin{verbatim}
+lua_State *lua_newstate (void) {
+  lua_State *old = lua_setstate(NULL);
+  lua_open();
+  return lua_setstate(old);
+}
+\end{verbatim}
+This function creates a new state without changing the current state
+of the interpreter.
+Notice that any new state is built with all predefined functions;
+any additional library (such as the standard libraries) must be
+explicitly open in the new state, if needed.
+
+If necessary, a state may be released:\Deffunc{lua_close}
 \begin{verbatim}
 void           lua_close                (void);
 \end{verbatim}
-This function destroys all objects in the Lua environment
+This function destroys all objects in the current Lua environment
 (calling the correspondent garbage collector tag methods),
-and then frees all dynamic memory used by the library.
+frees all dynamic memory used by the state,
+and then sets \verb|lua_state| to \verb|NULL|.
 Usually, there is no need to call this function,
 since these resources are naturally released when the program ends.
-If the library is already closed,
+If \verb|lua_state| is already \verb|NULL|,
 this function has no effect.
 
+If you are using multiple states,
+you may find useful the following function,
+which releases a given state:
+\begin{verbatim}
+void lua_freestate (lua_State *st) {
+  lua_State *old = lua_setstate(st);
+  lua_close();
+  if (old != st) lua_setstate(old);
+}
+\end{verbatim}
+
 \subsection{Exchanging Values between C and Lua} \label{valuesCLua}
 Because Lua has no static type system,
 all values passed between Lua and C have type
@@ -1522,12 +1569,13 @@ The use of explicit nested blocks is strongly encouraged.
 \subsection{Executing Lua Code}
 A host program can execute Lua chunks written in a file or in a string
 using the following functions:
-\Deffunc{lua_dofile}\Deffunc{lua_dostring}
+\Deffunc{lua_dofile}\Deffunc{lua_dostring}\Deffunc{lua_dobuffer}
 \begin{verbatim}
 int lua_dofile   (char *filename);
 int lua_dostring (char *string);
+int lua_dobuffer (char *buff, int size);
 \end{verbatim}
-Both functions return an error code:
+All these functions return an error code:
 0, in case of success; non zero, in case of errors.
 More specifically, \verb|lua_dofile| returns 2 if for any reason
 it could not open the file.
@@ -1536,6 +1584,8 @@ executes the \verb|stdin| stream.
 Function \verb|lua_dofile| is also able to execute pre-compiled chunks.
 It automatically detects whether the file is text or binary,
 and loads it accordingly (see program \IndexVerb{luac}).
+Function \verb|lua_dostring| executes only source code,
+and function \verb|lua_dobuffer| executes only pre-compiled chunks.
 
 These functions return, in structure lua2C,
 any values eventually returned by the chunks.
@@ -1975,7 +2025,7 @@ converts it to a string in a reasonable format.
 
 \subsubsection*{\ff \T{print (e1, e2, ...)}}\Deffunc{print}
 This function receives any number of arguments,
-and prints their values in a reasonable format.
+and prints their values using the strings returned by \verb|tostring|.
 This function is not intended for formatted output,
 but as a quick way to show a value,
 for instance for error messages or debugging.
@@ -2177,7 +2227,7 @@ letter depends on the current locale.
 Returns a string that is the concatenation of \verb|n| copies of
 the string \verb|s|.
 
-\subsubsection*{\ff \T{ascii (s [, i])}}\Deffunc{ascii}
+\subsubsection*{\ff \T{strbyte (s [, i])}}\Deffunc{strbyte}
 Returns the internal numerical code of the character \verb|s[i]|.
 If \verb|i| is absent, then it is assumed to be 1.
 If \verb|i| is negative,
@@ -2185,10 +2235,10 @@ it is replaced by the length of the string minus its
 absolute value plus 1.
 Therefore, \M{-1} points to the last character of \verb|s|.
 
-\subsubsection*{\ff \T{int2str (i1, i2, \ldots)}}\Deffunc{int2str}
+\subsubsection*{\ff \T{strchar (i1, i2, \ldots)}}\Deffunc{strchar}
 Receives 0 or more integers.
 Returns a string with length equal to the number of arguments,
-wherein each character has ascii value equal
+wherein each character has the internal numerical code equal
 to its correspondent argument.
 
 \subsubsection*{\ff \T{format (formatstring, e1, e2, \ldots)}}\Deffunc{format}