RE: Ref manual; lua_State documentation

["Thijs Schreijer" <thijs@...>]

> -----Original Message-----
> From: lua-l-bounces@lists.lua.org [mailto:lua-l-bounces@lists.lua.org]
> On Behalf Of Roberto Ierusalimschy
> Sent: vrijdag 11 mei 2012 19:37
> To: Lua mailing list
> Subject: Re: Ref manual; lua_State documentation
> 
> > The reference manual (5.2) says this;
> >
> > > typedef struct lua_State lua_State;
> > >
> > > An opaque structure that keeps the whole state of
> > > a Lua interpreter. The Lua library is fully
> > > reentrant: it has no global variables. All
> > > information about a state is kept in this structure.
> > >
> > > A pointer to this state must be passed as the first
> > > argument to every function in the library, except to
> > > lua_newstate, which creates a Lua state from scratch.
> >
> > And at thread creation it says;
> > > lua_newthread
> > > lua_State *lua_newthread (lua_State *L);
> > >
> > > Creates a new thread, pushes it on the stack, and
> > > returns a pointer to a lua_State that represents this
> > > new thread. The new thread returned by this function
> > > shares with the original thread its global environment,
> > > but has an independent execution stack.
> > >
> > > There is no explicit function to close or to destroy a
> > > thread. Threads are subject to garbage collection, like
> > > any Lua object.
> >
> > Seems conflicting to me, as the newthread only creates a thread, but
> still
> > returns a lua_State. Is then the lua_State description outdated?
> 
> lua_State points to threads and threads point to the global state, so
> a lua_State indirectly points to the global state. We will try to
> clarify that in the manual.
> 
> 
> > Also pops the question what happens when you call lua_close() with a
> > lua_State created by lua_newthread().
> 
> It closes the state associated with that thread.
> 
> -- Roberto

As a suggestion, maybe lua_State should then be renamed to lua_Stack, to
make it more explicit in the code as well.