aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorRoberto Ierusalimschy <roberto@inf.puc-rio.br>2023-12-07 15:45:11 -0300
committerRoberto Ierusalimschy <roberto@inf.puc-rio.br>2023-12-07 15:45:11 -0300
commit925fe8a0f2a667c96c015ee74d1a702af9ea5507 (patch)
treebca1cb92e11218498f4c76f651f4a5fa1a8c87b5 /manual
parent789e7acdea3ada96bd00b7aac6d82e805bfee85c (diff)
downloadlua-925fe8a0f2a667c96c015ee74d1a702af9ea5507.tar.gz
lua-925fe8a0f2a667c96c015ee74d1a702af9ea5507.tar.bz2
lua-925fe8a0f2a667c96c015ee74d1a702af9ea5507.zip
First criteria for shifts minor<->major
Diffstat (limited to 'manual')
-rw-r--r--manual/manual.of134
1 files changed, 77 insertions, 57 deletions
diff --git a/manual/manual.of b/manual/manual.of
index 263ced72..8607e57d 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -621,7 +621,8 @@ that is inaccessible from Lua.
621another live object refer to the object.) 621another live object refer to the object.)
622Because Lua has no knowledge about @N{C code}, 622Because Lua has no knowledge about @N{C code},
623it never collects objects accessible through the registry @see{registry}, 623it never collects objects accessible through the registry @see{registry},
624which includes the global environment @see{globalenv}. 624which includes the global environment @see{globalenv} and
625the main thread.
625 626
626 627
627The garbage collector (GC) in Lua can work in two modes: 628The garbage collector (GC) in Lua can work in two modes:
@@ -638,8 +639,8 @@ therefore, optimal settings are also non-portable.
638You can change the GC mode and parameters by calling 639You can change the GC mode and parameters by calling
639@Lid{lua_gc} @N{in C} 640@Lid{lua_gc} @N{in C}
640or @Lid{collectgarbage} in Lua. 641or @Lid{collectgarbage} in Lua.
641You can also use these functions to control 642You can also use these functions to control the collector directly,
642the collector directly (e.g., to stop and restart it). 643for instance to stop or restart it.
643 644
644} 645}
645 646
@@ -656,39 +657,36 @@ and the @def{garbage-collector step size}.
656 657
657The garbage-collector pause 658The garbage-collector pause
658controls how long the collector waits before starting a new cycle. 659controls how long the collector waits before starting a new cycle.
659The collector starts a new cycle when the use of memory 660The collector starts a new cycle when the number of objects
660hits @M{n%} of the use after the previous collection. 661hits @M{n%} of the total after the previous collection.
661Larger values make the collector less aggressive. 662Larger values make the collector less aggressive.
662Values equal to or less than 100 mean the collector will not wait to 663Values equal to or less than 100 mean the collector will not wait to
663start a new cycle. 664start a new cycle.
664A value of 200 means that the collector waits for the total memory in use 665A value of 200 means that the collector waits for
665to double before starting a new cycle. 666the total number of objects to double before starting a new cycle.
666The default value is 200; the maximum value is 1000. 667The default value is 200; the maximum value is 1000.
667 668
668The garbage-collector step multiplier 669The garbage-collector step multiplier
669controls the speed of the collector relative to 670controls the speed of the collector relative to
670memory allocation, 671object creation,
671that is, 672that is,
672how many elements it marks or sweeps for each 673how many objects it marks or sweeps for each object created.
673kilobyte of memory allocated. 674Larger values make the collector more aggressive.
674Larger values make the collector more aggressive but also increase 675Beware that values too small can
675the size of each incremental step. 676make the collector too slow to ever finish a cycle.
676You should not use values less than 100, 677The default value is 300; the maximum value is 1000.
677because they make the collector too slow and
678can result in the collector never finishing a cycle.
679The default value is 100; the maximum value is 1000.
680 678
681The garbage-collector step size controls the 679The garbage-collector step size controls the
682size of each incremental step, 680size of each incremental step,
683specifically how many bytes the interpreter allocates 681specifically how many objects the interpreter creates
684before performing a step. 682before performing a step.
685This parameter is logarithmic: 683This parameter is logarithmic:
686A value of @M{n} means the interpreter will allocate @M{2@sp{n}} 684A value of @M{n} means the interpreter will create @M{2@sp{n}}
687bytes between steps and perform equivalent work during the step. 685objects between steps and perform equivalent work during the step.
688A large value (e.g., 60) makes the collector a stop-the-world 686A large value (e.g., 60) makes the collector a stop-the-world
689(non-incremental) collector. 687(non-incremental) collector.
690The default value is 13, 688The default value is 8,
691which means steps of approximately @N{8 Kbytes}. 689which means steps of approximately @N{256 objects}.
692 690
693} 691}
694 692
@@ -697,31 +695,44 @@ which means steps of approximately @N{8 Kbytes}.
697In generational mode, 695In generational mode,
698the collector does frequent @emph{minor} collections, 696the collector does frequent @emph{minor} collections,
699which traverses only objects recently created. 697which traverses only objects recently created.
700If after a minor collection the use of memory is still above a limit, 698If after a minor collection the number of objects is above a limit,
701the collector does a stop-the-world @emph{major} collection, 699the collector shifts to a @emph{major} collection,
702which traverses all objects. 700which traverses all objects.
703The generational mode uses two parameters: 701The collector will then stay doing major collections until
704the @def{minor multiplier} and the @def{the major multiplier}. 702it detects that the program is generating enough garbage to justify
703going back to minor collections.
704
705The generational mode uses three parameters:
706the @def{minor multiplier}, the @def{minor-major multiplier},
707and the @def{major-minor multiplier}.
705 708
706The minor multiplier controls the frequency of minor collections. 709The minor multiplier controls the frequency of minor collections.
707For a minor multiplier @M{x}, 710For a minor multiplier @M{x},
708a new minor collection will be done when memory 711a new minor collection will be done when the number of objects
709grows @M{x%} larger than the memory in use after the previous major 712grows @M{x%} larger than the number in use just after the last collection.
710collection.
711For instance, for a multiplier of 20, 713For instance, for a multiplier of 20,
712the collector will do a minor collection when the use of memory 714the collector will do a minor collection when the number of objects
713gets 20% larger than the use after the previous major collection. 715gets 20% larger than the total after the last major collection.
714The default value is 20; the maximum value is 200. 716The default value is 20.
715 717
716The major multiplier controls the frequency of major collections. 718The minor-major multiplier controls the shift to major collections.
717For a major multiplier @M{x}, 719For a multiplier @M{x},
718a new major collection will be done when memory 720the collector will shift to a major collection
719grows @M{x%} larger than the memory in use after the previous major 721when the number of old objects grows @M{x%} larger
720collection. 722than the total after the previous major collection.
721For instance, for a multiplier of 100, 723For instance, for a multiplier of 100,
722the collector will do a major collection when the use of memory 724the collector will do a major collection when the number of old objects
723gets larger than twice the use after the previous collection. 725gets larger than twice the total after the previous major collection.
724The default value is 100; the maximum value is 1000. 726The default value is 100.
727
728The major-minor multiplier controls the shift back to minor collections.
729For a multiplier @M{x},
730the collector will shift back to minor collections
731after a major collection collects at least @M{x%} of the allocated objects.
732In particular, for a multiplier of 0,
733the collector will immediately shift back to minor collections
734after doing one cycle of major collections.
735The default value is 20.
725 736
726} 737}
727 738
@@ -3311,9 +3322,8 @@ Returns the remainder of dividing the current amount of bytes of
3311memory in use by Lua by 1024. 3322memory in use by Lua by 1024.
3312} 3323}
3313 3324
3314@item{@id{LUA_GCSTEP} @T{(int stepsize)}| 3325@item{@id{LUA_GCSTEP}|
3315Performs an incremental step of garbage collection, 3326Performs a step of garbage collection.
3316corresponding to the allocation of @id{stepsize} Kbytes.
3317} 3327}
3318 3328
3319@item{@id{LUA_GCISRUNNING}| 3329@item{@id{LUA_GCISRUNNING}|
@@ -3321,13 +3331,13 @@ Returns a boolean that tells whether the collector is running
3321(i.e., not stopped). 3331(i.e., not stopped).
3322} 3332}
3323 3333
3324@item{@id{LUA_GCINC} (int pause, int stepmul, stepsize)| 3334@item{@id{LUA_GCINC} (int pause, int stepmul, int stepsize)|
3325Changes the collector to incremental mode 3335Changes the collector to incremental mode
3326with the given parameters @see{incmode}. 3336with the given parameters @see{incmode}.
3327Returns the previous mode (@id{LUA_GCGEN} or @id{LUA_GCINC}). 3337Returns the previous mode (@id{LUA_GCGEN} or @id{LUA_GCINC}).
3328} 3338}
3329 3339
3330@item{@id{LUA_GCGEN} (int minormul, int majormul)| 3340@item{@id{LUA_GCGEN} (int minormul, int minormajor, int majorminor)|
3331Changes the collector to generational mode 3341Changes the collector to generational mode
3332with the given parameters @see{genmode}. 3342with the given parameters @see{genmode}.
3333Returns the previous mode (@id{LUA_GCGEN} or @id{LUA_GCINC}). 3343Returns the previous mode (@id{LUA_GCGEN} or @id{LUA_GCINC}).
@@ -6312,13 +6322,14 @@ gives the exact number of bytes in use by Lua.
6312 6322
6313@item{@St{step}| 6323@item{@St{step}|
6314Performs a garbage-collection step. 6324Performs a garbage-collection step.
6315The step @Q{size} is controlled by @id{arg}. 6325In incremental mode,
6316With a zero value, 6326that step corresponds to the current step size;
6317the collector will perform one basic (indivisible) step. 6327the function returns @true if the step finished a collection cycle.
6318For non-zero values, 6328In generational mode,
6319the collector will perform as if that amount of memory 6329the step performs a full minor collection or
6320(in Kbytes) had been allocated by Lua. 6330a major collection,
6321Returns @true if the step finished a collection cycle. 6331if the collector has scheduled one;
6332the function returns @true if the step performed a major collection.
6322} 6333}
6323 6334
6324@item{@St{isrunning}| 6335@item{@St{isrunning}|
@@ -6332,15 +6343,15 @@ This option can be followed by three numbers:
6332the garbage-collector pause, 6343the garbage-collector pause,
6333the step multiplier, 6344the step multiplier,
6334and the step size @see{incmode}. 6345and the step size @see{incmode}.
6335A zero means to not change that value. 6346A -1 or absent value means to not change that value.
6336} 6347}
6337 6348
6338@item{@St{generational}| 6349@item{@St{generational}|
6339Change the collector mode to generational. 6350Change the collector mode to generational.
6340This option can be followed by two numbers: 6351This option can be followed by three numbers:
6341the garbage-collector minor multiplier 6352the garbage-collector minor multiplier,
6342and the major multiplier @see{genmode}. 6353the minor-major multiplier, and the major-minor multiplier @see{genmode}.
6343A zero means to not change that value. 6354A -1 or absent value means to not change that value.
6344} 6355}
6345 6356
6346} 6357}
@@ -9229,6 +9240,9 @@ declare a local variable with the same name in the loop body.
9229@itemize{ 9240@itemize{
9230 9241
9231@item{ 9242@item{
9243There were several changes in the parameters
9244for the options @St{incremental} and @St{generational}
9245of the function @Lid{collectgarbage}.
9232} 9246}
9233 9247
9234} 9248}
@@ -9245,6 +9259,12 @@ it is equivalent to @Lid{lua_closethread} with
9245@id{from} being @id{NULL}. 9259@id{from} being @id{NULL}.
9246} 9260}
9247 9261
9262@item{
9263There were several changes in the parameters
9264for the options @Lid{LUA_GCINC} and @Lid{LUA_GCGEN}
9265of the function @Lid{lua_gc}.
9266}
9267
9248} 9268}
9249 9269
9250} 9270}