From 02a6891939895129bc968364a5beda73331005e7 Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Tue, 2 Jun 1998 17:37:04 -0300 Subject: API for functions to manipulate global state. --- lbuffer.c | 4 +-- lstate.c | 14 ++++++++--- lstate.h | 23 ++++++++++-------- lua.h | 7 +++++- manual.tex | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++------------ 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} -- cgit v1.2.3-55-g6feb