aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorRoberto Ierusalimschy <roberto@inf.puc-rio.br>2024-01-15 11:31:49 -0300
committerRoberto Ierusalimschy <roberto@inf.puc-rio.br>2024-01-15 11:31:49 -0300
commit17e0c29d9b435392016b707309ed51409b0aea12 (patch)
treec7178cf68fac2f1f9c3b22ce50be29b67f416cc0 /manual
parent8eb0abc9db4d47db5192bed18565e3d1aa53566d (diff)
downloadlua-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.of26
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
2645uppercase letters are reserved for Lua. 2645uppercase letters are reserved for Lua.
2646 2646
2647The integer keys in the registry are used 2647The integer keys in the registry are used
2648by the reference mechanism @seeC{luaL_ref} 2648by the reference mechanism @seeC{luaL_ref},
2649and by some predefined values. 2649with some predefined values.
2650Therefore, integer keys in the registry 2650Therefore, integer keys in the registry
2651must not be used for other purposes. 2651must not be used for other purposes.
2652 2652
@@ -6018,11 +6018,21 @@ Creates and returns a @def{reference},
6018in the table at index @id{t}, 6018in the table at index @id{t},
6019for the object on the top of the stack (and pops the object). 6019for the object on the top of the stack (and pops the object).
6020 6020
6021A reference is a unique integer key. 6021The reference system uses the integer keys of the table.
6022As long as you do not manually add integer keys into the table @id{t}, 6022A 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.
6024The entry 1 is reserved for internal use.
6025Before the first use of @Lid{luaL_ref},
6026the integer keys of the table
6027should form a proper sequence (no holes),
6028and the value at entry 1 should be false:
6029@nil if the sequence is empty,
6030@false otherwise.
6031You should not manually set integer keys in the table
6032after the first use of @Lid{luaL_ref}.
6033
6024You can retrieve an object referred by the reference @id{r} 6034You can retrieve an object referred by the reference @id{r}
6025by calling @T{lua_rawgeti(L, t, r)}. 6035by calling @T{lua_rawgeti(L, t, r)} or @T{lua_geti(L, t, r)}.
6026The function @Lid{luaL_unref} frees a reference. 6036The function @Lid{luaL_unref} frees a reference.
6027 6037
6028If the object on the top of the stack is @nil, 6038If 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.
6188Releases the reference @id{ref} from the table at index @id{t} 6198Releases the reference @id{ref} from the table at index @id{t}
6189@seeC{luaL_ref}. 6199@seeC{luaL_ref}.
6190The entry is removed from the table, 6200The entry is removed from the table,
6191so that the referred object can be collected. 6201so that the referred object can be collected and
6192The reference @id{ref} is also freed to be used again. 6202the reference @id{ref} can be used again by @Lid{luaL_ref}.
6193 6203
6194If @id{ref} is @Lid{LUA_NOREF} or @Lid{LUA_REFNIL}, 6204If @id{ref} is @Lid{LUA_NOREF} or @Lid{LUA_REFNIL},
6195@Lid{luaL_unref} does nothing. 6205@Lid{luaL_unref} does nothing.