aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorRoberto Ierusalimschy <roberto@inf.puc-rio.br>2018-11-13 14:33:14 -0200
committerRoberto Ierusalimschy <roberto@inf.puc-rio.br>2018-11-13 14:33:14 -0200
commitbb0185b196773b878f0bf6b6c6a4a01dbf8c2b83 (patch)
treefdafab0746428bf051545aca598f5877089b4ba1 /manual
parentd40cd315f50538e9dbd4362a4763c01527f4eb3a (diff)
downloadlua-bb0185b196773b878f0bf6b6c6a4a01dbf8c2b83.tar.gz
lua-bb0185b196773b878f0bf6b6c6a4a01dbf8c2b83.tar.bz2
lua-bb0185b196773b878f0bf6b6c6a4a01dbf8c2b83.zip
Documentation for to-be-closed variables
Diffstat (limited to 'manual')
-rw-r--r--manual/manual.of148
1 files changed, 122 insertions, 26 deletions
diff --git a/manual/manual.of b/manual/manual.of
index 91ba8c46..f891c33e 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -1448,7 +1448,9 @@ for @rep{var_1}, @Cdots, @rep{var_n} in @rep{explist} do @rep{block} end
1448is equivalent to the code: 1448is equivalent to the code:
1449@verbatim{ 1449@verbatim{
1450do 1450do
1451 local @rep{f}, @rep{s}, @rep{var} = @rep{explist} 1451 local @rep{f}, @rep{s}, @rep{var}
1452 local *toclose @rep{tbc} = nil
1453 @rep{f}, @rep{s}, @rep{var}, @rep{tbc} = @rep{explist}
1452 while true do 1454 while true do
1453 local @rep{var_1}, @Cdots, @rep{var_n} = @rep{f}(@rep{s}, @rep{var}) 1455 local @rep{var_1}, @Cdots, @rep{var_n} = @rep{f}(@rep{s}, @rep{var})
1454 if @rep{var_1} == nil then break end 1456 if @rep{var_1} == nil then break end
@@ -1464,11 +1466,14 @@ Note the following:
1464@T{@rep{explist}} is evaluated only once. 1466@T{@rep{explist}} is evaluated only once.
1465Its results are an @emph{iterator} function, 1467Its results are an @emph{iterator} function,
1466a @emph{state}, 1468a @emph{state},
1467and an initial value for the first @emph{iterator variable}. 1469an initial value for the first @emph{iterator variable},
1470and a to-be-closed variable @see{to-be-closed},
1471which can be used to release resources when the loop ends.
1468} 1472}
1469 1473
1470@item{ 1474@item{
1471@T{@rep{f}}, @T{@rep{s}}, and @T{@rep{var}} are invisible variables. 1475@T{@rep{f}}, @T{@rep{s}}, @T{@rep{var}}, and @T{@rep{tbc}}
1476are invisible variables.
1472The names are here for explanatory purposes only. 1477The names are here for explanatory purposes only.
1473} 1478}
1474 1479
@@ -1515,6 +1520,52 @@ The visibility rules for local variables are explained in @See{visibility}.
1515 1520
1516} 1521}
1517 1522
1523@sect3{to-be-closed| @title{To-be-closed Variables}
1524
1525A local variable can be declared as a @def{to-be-closed} variable,
1526with the following syntax:
1527@Produc{
1528@producname{stat}@producbody{
1529 @Rw{local} @bnfter{*} @bnfter{toclose} Name @bnfter{=} exp
1530}}
1531A to-be-closed variable behaves like a normal local variable,
1532except that its value is @emph{closed} whenever the variable
1533goes out of scope, including normal block termination,
1534exiting its block by @Rw{break}/@Rw{goto}/@Rw{return},
1535or exiting by an error.
1536If a block ends in a tail call @see{functioncall},
1537all variables of the caller function go out of scope
1538before the start of the callee function.
1539
1540To \emph{close} a value has the following meaning here:
1541If the value of the variable when it goes out of scope is a function,
1542that function is called;
1543otherwise, if the value has a @idx{__close} metamethod,
1544that metamethod is called;
1545otherwise, nothing is done.
1546In the function case,
1547if the scope is being closed by an error,
1548the error object is passed as an argument to the function;
1549if there is no error, the function gets @nil.
1550In the metamethod case,
1551the value itself always is passed as an argument to the metamethod.
1552
1553If several to-be-closed variables go out of scope at the same event,
1554they are closed in the reverse order that they were declared.
1555If there is any error while running a closing function,
1556that error is handled like an error in the regular code
1557where the variable was defined;
1558in particular,
1559the other pending closing functions will still be called.
1560
1561If a coroutine yields inside a block and is never resumed again,
1562the variables visible at that block will never go out of scope,
1563and therefore they will not be closed.
1564Similarly, if a script is interrupted by an unprotected error,
1565its to-be-closed variables will not be closed.
1566
1567}
1568
1518} 1569}
1519 1570
1520@sect2{expressions| @title{Expressions} 1571@sect2{expressions| @title{Expressions}
@@ -2442,7 +2493,7 @@ the result of @Lid{lua_newthread}),
2442it should use them only in API calls that cannot raise errors. 2493it should use them only in API calls that cannot raise errors.
2443 2494
2444The panic function runs as if it were a @x{message handler} @see{error}; 2495The panic function runs as if it were a @x{message handler} @see{error};
2445in particular, the error object is at the top of the stack. 2496in particular, the error object is on the top of the stack.
2446However, there is no guarantee about stack space. 2497However, there is no guarantee about stack space.
2447To push anything on the stack, 2498To push anything on the stack,
2448the panic function must first check the available space @see{stacksize}. 2499the panic function must first check the available space @see{stacksize}.
@@ -2593,9 +2644,9 @@ tells whether the function may raise errors:
2593@Char{m} means the function may raise out-of-memory errors 2644@Char{m} means the function may raise out-of-memory errors
2594and errors running a finalizer; 2645and errors running a finalizer;
2595@Char{v} means the function may raise the errors explained in the text; 2646@Char{v} means the function may raise the errors explained in the text;
2596@Char{e} means the function may raise any errors 2647@Char{e} means the function can run arbitrary Lua code,
2597(because it can run arbitrary Lua code, 2648either directly or through metamethods,
2598either directly or through metamethods). 2649and therefore may raise any errors.
2599 2650
2600 2651
2601@APIEntry{int lua_absindex (lua_State *L, int idx);| 2652@APIEntry{int lua_absindex (lua_State *L, int idx);|
@@ -2675,7 +2726,7 @@ that @T{free(NULL)} has no effect and that
2675Performs an arithmetic or bitwise operation over the two values 2726Performs an arithmetic or bitwise operation over the two values
2676(or one, in the case of negations) 2727(or one, in the case of negations)
2677at the top of the stack, 2728at the top of the stack,
2678with the value at the top being the second operand, 2729with the value on the top being the second operand,
2679pops these values, and pushes the result of the operation. 2730pops these values, and pushes the result of the operation.
2680The function follows the semantics of the corresponding Lua operator 2731The function follows the semantics of the corresponding Lua operator
2681(that is, it may call metamethods). 2732(that is, it may call metamethods).
@@ -2875,7 +2926,7 @@ The value of @id{op} must be one of the following constants:
2875@apii{n,1,e} 2926@apii{n,1,e}
2876 2927
2877Concatenates the @id{n} values at the top of the stack, 2928Concatenates the @id{n} values at the top of the stack,
2878pops them, and leaves the result at the top. 2929pops them, and leaves the result on the top.
2879If @N{@T{n} is 1}, the result is the single value on the stack 2930If @N{@T{n} is 1}, the result is the single value on the stack
2880(that is, the function does nothing); 2931(that is, the function does nothing);
2881if @id{n} is 0, the result is the empty string. 2932if @id{n} is 0, the result is the empty string.
@@ -2942,7 +2993,7 @@ This function does not pop the Lua function from the stack.
2942@apii{1,0,v} 2993@apii{1,0,v}
2943 2994
2944Generates a Lua error, 2995Generates a Lua error,
2945using the value at the top of the stack as the error object. 2996using the value on the top of the stack as the error object.
2946This function does a long jump, 2997This function does a long jump,
2947and therefore never returns 2998and therefore never returns
2948@seeC{luaL_error}. 2999@seeC{luaL_error}.
@@ -3081,7 +3132,7 @@ the function @N{returns 0} and pushes nothing on the stack.
3081 3132
3082Pushes onto the stack the value @T{t[k]}, 3133Pushes onto the stack the value @T{t[k]},
3083where @id{t} is the value at the given index 3134where @id{t} is the value at the given index
3084and @id{k} is the value at the top of the stack. 3135and @id{k} is the value on the top of the stack.
3085 3136
3086This function pops the key from the stack, 3137This function pops the key from the stack,
3087pushing the resulting value in its place. 3138pushing the resulting value in its place.
@@ -3798,7 +3849,7 @@ Similar to @Lid{lua_settable}, but does a raw assignment
3798 3849
3799Does the equivalent of @T{t[i] = v}, 3850Does the equivalent of @T{t[i] = v},
3800where @id{t} is the table at the given index 3851where @id{t} is the table at the given index
3801and @id{v} is the value at the top of the stack. 3852and @id{v} is the value on the top of the stack.
3802 3853
3803This function pops the value from the stack. 3854This function pops the value from the stack.
3804The assignment is raw, 3855The assignment is raw,
@@ -3812,7 +3863,7 @@ that is, it does not invoke the @idx{__newindex} metamethod.
3812Does the equivalent of @T{t[p] = v}, 3863Does the equivalent of @T{t[p] = v},
3813where @id{t} is the table at the given index, 3864where @id{t} is the table at the given index,
3814@id{p} is encoded as a light userdata, 3865@id{p} is encoded as a light userdata,
3815and @id{v} is the value at the top of the stack. 3866and @id{v} is the value on the top of the stack.
3816 3867
3817This function pops the value from the stack. 3868This function pops the value from the stack.
3818The assignment is raw, 3869The assignment is raw,
@@ -3939,7 +3990,7 @@ with user data @id{ud}.
3939 3990
3940Does the equivalent to @T{t[k] = v}, 3991Does the equivalent to @T{t[k] = v},
3941where @id{t} is the value at the given index 3992where @id{t} is the value at the given index
3942and @id{v} is the value at the top of the stack. 3993and @id{v} is the value on the top of the stack.
3943 3994
3944This function pops the value from the stack. 3995This function pops the value from the stack.
3945As in Lua, this function may trigger a metamethod 3996As in Lua, this function may trigger a metamethod
@@ -3960,7 +4011,7 @@ sets it as the new value of global @id{name}.
3960 4011
3961Does the equivalent to @T{t[n] = v}, 4012Does the equivalent to @T{t[n] = v},
3962where @id{t} is the value at the given index 4013where @id{t} is the value at the given index
3963and @id{v} is the value at the top of the stack. 4014and @id{v} is the value on the top of the stack.
3964 4015
3965This function pops the value from the stack. 4016This function pops the value from the stack.
3966As in Lua, this function may trigger a metamethod 4017As in Lua, this function may trigger a metamethod
@@ -3981,7 +4032,7 @@ sets it as the new metatable for the value at the given index.
3981 4032
3982Does the equivalent to @T{t[k] = v}, 4033Does the equivalent to @T{t[k] = v},
3983where @id{t} is the value at the given index, 4034where @id{t} is the value at the given index,
3984@id{v} is the value at the top of the stack, 4035@id{v} is the value on the top of the stack,
3985and @id{k} is the value just below the top. 4036and @id{k} is the value just below the top.
3986 4037
3987This function pops both the key and the value from the stack. 4038This function pops both the key and the value from the stack.
@@ -4082,6 +4133,31 @@ otherwise, returns @id{NULL}.
4082 4133
4083} 4134}
4084 4135
4136@APIEntry{void lua_toclose (lua_State *L, int index);|
4137@apii{0,0,v}
4138
4139Marks the given index in the stack as a
4140to-be-closed @Q{variable} @see{to-be-closed}.
4141Like a to-be-closed variable in Lua,
4142the value at that index in the stack will be closed
4143when it goes out of scope.
4144Here, in the context of a C function,
4145to go out of scope means that the running function returns (to Lua),
4146there is an error,
4147or the index is removed from the stack through
4148@Lid{lua_settop} or @Lid{lua_pop}.
4149An index marked as to-be-closed should not be removed from the stack
4150by any other function in the API except @Lid{lua_settop} or @Lid{lua_pop}.
4151
4152This function should not be called for an index
4153that is equal to or below an already marked to-be-closed index.
4154
4155This function can raise an out-of-memory error.
4156In that case, the value in the given index is immediately closed,
4157as if it was already marked.
4158
4159}
4160
4085@APIEntry{lua_Integer lua_tointeger (lua_State *L, int index);| 4161@APIEntry{lua_Integer lua_tointeger (lua_State *L, int index);|
4086@apii{0,0,-} 4162@apii{0,0,-}
4087 4163
@@ -4587,7 +4663,7 @@ and names.
4587and returns its name. 4663and returns its name.
4588 4664
4589In the second case, @id{ar} must be @id{NULL} and the function 4665In the second case, @id{ar} must be @id{NULL} and the function
4590to be inspected must be at the top of the stack. 4666to be inspected must be on the top of the stack.
4591In this case, only parameters of Lua functions are visible 4667In this case, only parameters of Lua functions are visible
4592(as there is no information about what variables are active) 4668(as there is no information about what variables are active)
4593and no values are pushed onto the stack. 4669and no values are pushed onto the stack.
@@ -4720,7 +4796,7 @@ A hook is disabled by setting @id{mask} to zero.
4720@apii{0|1,0,-} 4796@apii{0|1,0,-}
4721 4797
4722Sets the value of a local variable of a given activation record. 4798Sets the value of a local variable of a given activation record.
4723It assigns the value at the top of the stack 4799It assigns the value on the top of the stack
4724to the variable and returns its name. 4800to the variable and returns its name.
4725It also pops the value from the stack. 4801It also pops the value from the stack.
4726 4802
@@ -4736,7 +4812,7 @@ Parameters @id{ar} and @id{n} are as in function @Lid{lua_getlocal}.
4736@apii{0|1,0,-} 4812@apii{0|1,0,-}
4737 4813
4738Sets the value of a closure's upvalue. 4814Sets the value of a closure's upvalue.
4739It assigns the value at the top of the stack 4815It assigns the value on the top of the stack
4740to the upvalue and returns its name. 4816to the upvalue and returns its name.
4741It also pops the value from the stack. 4817It also pops the value from the stack.
4742 4818
@@ -4861,7 +4937,7 @@ to the buffer @id{B}
4861@APIEntry{void luaL_addvalue (luaL_Buffer *B);| 4937@APIEntry{void luaL_addvalue (luaL_Buffer *B);|
4862@apii{1,?,m} 4938@apii{1,?,m}
4863 4939
4864Adds the value at the top of the stack 4940Adds the value on the top of the stack
4865to the buffer @id{B} 4941to the buffer @id{B}
4866@seeC{luaL_Buffer}. 4942@seeC{luaL_Buffer}.
4867Pops the value. 4943Pops the value.
@@ -5486,7 +5562,7 @@ Equivalent to the sequence @Lid{luaL_addsize}, @Lid{luaL_pushresult}.
5486 5562
5487Creates and returns a @def{reference}, 5563Creates and returns a @def{reference},
5488in the table at index @id{t}, 5564in the table at index @id{t},
5489for the object at the top of the stack (and pops the object). 5565for the object on the top of the stack (and pops the object).
5490 5566
5491A reference is a unique integer key. 5567A reference is a unique integer key.
5492As long as you do not manually add integer keys into table @id{t}, 5568As long as you do not manually add integer keys into table @id{t},
@@ -5495,7 +5571,7 @@ You can retrieve an object referred by reference @id{r}
5495by calling @T{lua_rawgeti(L, t, r)}. 5571by calling @T{lua_rawgeti(L, t, r)}.
5496Function @Lid{luaL_unref} frees a reference and its associated object. 5572Function @Lid{luaL_unref} frees a reference and its associated object.
5497 5573
5498If the object at the top of the stack is @nil, 5574If the object on the top of the stack is @nil,
5499@Lid{luaL_ref} returns the constant @defid{LUA_REFNIL}. 5575@Lid{luaL_ref} returns the constant @defid{LUA_REFNIL}.
5500The constant @defid{LUA_NOREF} is guaranteed to be different 5576The constant @defid{LUA_NOREF} is guaranteed to be different
5501from any reference returned by @Lid{luaL_ref}. 5577from any reference returned by @Lid{luaL_ref}.
@@ -5554,7 +5630,7 @@ These values are popped from the stack after the registration.
5554@APIEntry{void luaL_setmetatable (lua_State *L, const char *tname);| 5630@APIEntry{void luaL_setmetatable (lua_State *L, const char *tname);|
5555@apii{0,0,-} 5631@apii{0,0,-}
5556 5632
5557Sets the metatable of the object at the top of the stack 5633Sets the metatable of the object on the top of the stack
5558as the metatable associated with name @id{tname} 5634as the metatable associated with name @id{tname}
5559in the registry @seeC{luaL_newmetatable}. 5635in the registry @seeC{luaL_newmetatable}.
5560 5636
@@ -7571,6 +7647,9 @@ The table @id{io} also provides
7571three predefined file handles with their usual meanings from C: 7647three predefined file handles with their usual meanings from C:
7572@defid{io.stdin}, @defid{io.stdout}, and @defid{io.stderr}. 7648@defid{io.stdin}, @defid{io.stdout}, and @defid{io.stderr}.
7573The I/O library never closes these files. 7649The I/O library never closes these files.
7650The metatable for file handles provides metamethods
7651for @idx{__gc} and @idx{__close} that try
7652to close the file when called.
7574 7653
7575Unless otherwise stated, 7654Unless otherwise stated,
7576all I/O functions return @nil on failure 7655all I/O functions return @nil on failure
@@ -7617,6 +7696,13 @@ and returns an iterator function that
7617works like @T{file:lines(@Cdots)} over the opened file. 7696works like @T{file:lines(@Cdots)} over the opened file.
7618When the iterator function detects the end of file, 7697When the iterator function detects the end of file,
7619it returns no values (to finish the loop) and automatically closes the file. 7698it returns no values (to finish the loop) and automatically closes the file.
7699Besides the iterator function,
7700@id{io.lines} returns three other values:
7701two @nil values as placeholders,
7702plus the created file handle.
7703Therefore, when used in a generic @Rw{for} loop,
7704the file is closed also if the loop is interrupted by an
7705error or a @Rw{break}.
7620 7706
7621The call @T{io.lines()} (with no file name) is equivalent 7707The call @T{io.lines()} (with no file name) is equivalent
7622to @T{io.input():lines("l")}; 7708to @T{io.input():lines("l")};
@@ -8543,6 +8629,13 @@ now starts with a somewhat random seed.
8543Moreover, it uses a different algorithm. 8629Moreover, it uses a different algorithm.
8544} 8630}
8545 8631
8632@item{
8633The function @Lid{io.lines} now returns three extra values,
8634besides the iterator function.
8635You can enclose the call in parentheses if you need to
8636discard these extra results.
8637}
8638
8546} 8639}
8547 8640
8548} 8641}
@@ -8559,15 +8652,17 @@ replaced by @Lid{lua_newuserdatauv},
8559@Lid{lua_setiuservalue}, and @Lid{lua_getiuservalue}, 8652@Lid{lua_setiuservalue}, and @Lid{lua_getiuservalue},
8560which have an extra argument. 8653which have an extra argument.
8561 8654
8562(For compatibility, the old names still work as macros assuming 8655For compatibility, the old names still work as macros assuming
8563one single user value.) 8656one single user value.
8657Note, however, that the call @T{lua_newuserdatauv(L,size,0)}
8658produces a smaller userdata.
8564} 8659}
8565 8660
8566@item{ 8661@item{
8567The function @Lid{lua_resume} has an extra parameter. 8662The function @Lid{lua_resume} has an extra parameter.
8568This out parameter returns the number of values on 8663This out parameter returns the number of values on
8569the top of the stack that were yielded or returned by the coroutine. 8664the top of the stack that were yielded or returned by the coroutine.
8570(In older versions, 8665(In previous versions,
8571those values were the entire stack.) 8666those values were the entire stack.)
8572} 8667}
8573 8668
@@ -8626,6 +8721,7 @@ and @bnfNter{LiteralString}, see @See{lexical}.)
8626@OrNL @Rw{function} funcname funcbody 8721@OrNL @Rw{function} funcname funcbody
8627@OrNL @Rw{local} @Rw{function} @bnfNter{Name} funcbody 8722@OrNL @Rw{local} @Rw{function} @bnfNter{Name} funcbody
8628@OrNL @Rw{local} namelist @bnfopt{@bnfter{=} explist} 8723@OrNL @Rw{local} namelist @bnfopt{@bnfter{=} explist}
8724@OrNL @Rw{local} @bnfter{*} @bnfter{toclose} Name @bnfter{=} exp
8629} 8725}
8630 8726
8631@producname{retstat}@producbody{@Rw{return} 8727@producname{retstat}@producbody{@Rw{return}