diff options
author | Roberto Ierusalimschy <roberto@inf.puc-rio.br> | 2024-01-15 11:31:49 -0300 |
---|---|---|
committer | Roberto Ierusalimschy <roberto@inf.puc-rio.br> | 2024-01-15 11:31:49 -0300 |
commit | 17e0c29d9b435392016b707309ed51409b0aea12 (patch) | |
tree | c7178cf68fac2f1f9c3b22ce50be29b67f416cc0 /manual | |
parent | 8eb0abc9db4d47db5192bed18565e3d1aa53566d (diff) | |
download | lua-17e0c29d9b435392016b707309ed51409b0aea12.tar.gz lua-17e0c29d9b435392016b707309ed51409b0aea12.tar.bz2 lua-17e0c29d9b435392016b707309ed51409b0aea12.zip |
Clear interface between references and predefines
The reference system has a defined way to add initial values to the
table where it operates.
Diffstat (limited to 'manual')
-rw-r--r-- | manual/manual.of | 26 |
1 files changed, 18 insertions, 8 deletions
diff --git a/manual/manual.of b/manual/manual.of index ae38d7c6..64bb5473 100644 --- a/manual/manual.of +++ b/manual/manual.of | |||
@@ -2645,8 +2645,8 @@ string keys starting with an underscore followed by | |||
2645 | uppercase letters are reserved for Lua. | 2645 | uppercase letters are reserved for Lua. |
2646 | 2646 | ||
2647 | The integer keys in the registry are used | 2647 | The integer keys in the registry are used |
2648 | by the reference mechanism @seeC{luaL_ref} | 2648 | by the reference mechanism @seeC{luaL_ref}, |
2649 | and by some predefined values. | 2649 | with some predefined values. |
2650 | Therefore, integer keys in the registry | 2650 | Therefore, integer keys in the registry |
2651 | must not be used for other purposes. | 2651 | must not be used for other purposes. |
2652 | 2652 | ||
@@ -6018,11 +6018,21 @@ Creates and returns a @def{reference}, | |||
6018 | in the table at index @id{t}, | 6018 | in the table at index @id{t}, |
6019 | for the object on the top of the stack (and pops the object). | 6019 | for the object on the top of the stack (and pops the object). |
6020 | 6020 | ||
6021 | A reference is a unique integer key. | 6021 | The reference system uses the integer keys of the table. |
6022 | As long as you do not manually add integer keys into the table @id{t}, | 6022 | A reference is a unique integer key; |
6023 | @Lid{luaL_ref} ensures the uniqueness of the key it returns. | 6023 | @Lid{luaL_ref} ensures the uniqueness of the keys it returns. |
6024 | The entry 1 is reserved for internal use. | ||
6025 | Before the first use of @Lid{luaL_ref}, | ||
6026 | the integer keys of the table | ||
6027 | should form a proper sequence (no holes), | ||
6028 | and the value at entry 1 should be false: | ||
6029 | @nil if the sequence is empty, | ||
6030 | @false otherwise. | ||
6031 | You should not manually set integer keys in the table | ||
6032 | after the first use of @Lid{luaL_ref}. | ||
6033 | |||
6024 | You can retrieve an object referred by the reference @id{r} | 6034 | You can retrieve an object referred by the reference @id{r} |
6025 | by calling @T{lua_rawgeti(L, t, r)}. | 6035 | by calling @T{lua_rawgeti(L, t, r)} or @T{lua_geti(L, t, r)}. |
6026 | The function @Lid{luaL_unref} frees a reference. | 6036 | The function @Lid{luaL_unref} frees a reference. |
6027 | 6037 | ||
6028 | If the object on the top of the stack is @nil, | 6038 | If the object on the top of the stack is @nil, |
@@ -6188,8 +6198,8 @@ Returns the name of the type of the value at the given index. | |||
6188 | Releases the reference @id{ref} from the table at index @id{t} | 6198 | Releases the reference @id{ref} from the table at index @id{t} |
6189 | @seeC{luaL_ref}. | 6199 | @seeC{luaL_ref}. |
6190 | The entry is removed from the table, | 6200 | The entry is removed from the table, |
6191 | so that the referred object can be collected. | 6201 | so that the referred object can be collected and |
6192 | The reference @id{ref} is also freed to be used again. | 6202 | the reference @id{ref} can be used again by @Lid{luaL_ref}. |
6193 | 6203 | ||
6194 | If @id{ref} is @Lid{LUA_NOREF} or @Lid{LUA_REFNIL}, | 6204 | If @id{ref} is @Lid{LUA_NOREF} or @Lid{LUA_REFNIL}, |
6195 | @Lid{luaL_unref} does nothing. | 6205 | @Lid{luaL_unref} does nothing. |