Re: Ref manual; lua_State documentation

[liam mail <liam.list@...>]

On 11 May 2012 19:59, Coda Highland <chighland@gmail.com> wrote:
> On Fri, May 11, 2012 at 1:42 PM, liam mail <liam.list@googlemail.com> wrote:
>> On 11 May 2012 19:25, Coda Highland <chighland@gmail.com> wrote:
>>> It may be opaque but there's still a relationship between them that
>>> needs documented.
>>
>> But "The reference manual is the official definition of the Lua
>> language."[1][2] and this is an implementation detail.
>>
>> [1] http://www.lua.org/manual/5.1/
>> [2] http://www.lua.org/manual/5.2/
>>
>> Liam
>>

I am all for improving documentation yet I am unsure what you are
proposing as the 5.2 manual has added more information about this
relationship[1][2][3][4].
>
> Coroutines are a documented function and the relationship between
> coroutines is well-defined.
I am sorry for I do not understand this.
A Coroutine being a lua_State* which was created by another state with
which it shares information, how can you say the relationship is
well-defined and then say

>As such, while the WAY two lua_States
> implement their information sharing is an implementation detail, the
> FACT that they share information is not. As such, it should be
> documented that two distinct lua_States can share global data and that
> coroutines are an example of how this might happen.
>
> /s/ Adam
>

[1]
lua_State *lua_newthread (lua_State *L)5.1
The new state returned by this function _shares with the original
state all global objects_ (such as tables), but has an independent
execution stack.
[2]
lua_State *lua_newthread (lua_State *L) 5.2
 The new thread returned by this function _shares with the original
thread its global environment_, but has an independent execution
stack.

[3]
5.2 2.6 coroutines
You can also create and manipulate coroutines through the C API: see
functions _lua_newthread_, lua_resume, and lua_yield.

[4]
5.2 4.5 registry
LUA_RIDX_MAINTHREAD: At this index the registry has the main thread of
the state. (The main thread is the one created together with the
state.)


Liam