X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fruntime_control.xml;h=22ca59dcd25b1b1f0551bc427d8c00828b69072c;hb=4df9f0ee56ae232e1cf2f9531205af0dd916b496;hp=d35027b73d1d8b54dd139a61b9b43502fbcbfab4;hpb=187b2ab71446eef91b1b5552f6202f3ee8ed2137;p=ghc-hetmet.git diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml index d35027b..22ca59d 100644 --- a/docs/users_guide/runtime_control.xml +++ b/docs/users_guide/runtime_control.xml @@ -10,7 +10,7 @@ code and then links it with a non-trivial runtime system (RTS), which handles storage management, profiling, etc. - If you use the -rtsopts flag when linking, + If you set the -rtsopts flag appropriately when linking, you have some control over the behaviour of the RTS, by giving special command-line arguments to your program. @@ -49,8 +49,8 @@ wraparound in the counters is your fault!) - Giving a +RTS -f - RTS option option + Giving a +RTS -? + RTS option option will print out the RTS options actually available in your program (which vary, depending on how you compiled). @@ -62,14 +62,15 @@ +RTS -M128m -RTS to the command line. - + Setting global RTS options RTS optionsfrom the environment environment variablefor setting RTS options - When the -rtsopts flag is used when linking, + If the -rtsopts flag is set to + something other than none when linking, RTS options are also taken from the environment variable GHCRTSGHCRTS . For example, to set the maximum heap size @@ -424,22 +425,88 @@ - size + size RTS option - stack, minimum size + stack, initial size - [Default: 1k] Set the initial stack size for - new threads. Thread stacks (including the main thread's - stack) live on the heap, and grow as required. The default - value is good for concurrent applications with lots of small - threads; if your program doesn't fit this model then - increasing this option may help performance. - - The main thread is normally started with a slightly - larger heap to cut down on unnecessary stack growth while - the program is starting up. - + + [Default: 1k] Set the initial stack size for new + threads. (Note: this flag used to be + simply , but was renamed + to in GHC 7.2.1. The old name is + still accepted for backwards compatibility, but that may + be removed in a future version). + + + + Thread stacks (including the main thread's stack) live on + the heap. As the stack grows, new stack chunks are added + as required; if the stack shrinks again, these extra stack + chunks are reclaimed by the garbage collector. The + default initial stack size is deliberately small, in order + to keep the time and space overhead for thread creation to + a minimum, and to make it practical to spawn threads for + even tiny pieces of work. + + + + + + + size + RTS + option + stackchunk size + + + + [Default: 32k] Set the size of “stack + chunks”. When a thread's current stack overflows, a + new stack chunk is created and added to the thread's + stack, until the limit set by is + reached. + + + + The advantage of smaller stack chunks is that the garbage + collector can avoid traversing stack chunks if they are + known to be unmodified since the last collection, so + reducing the chunk size means that the garbage collector + can identify more stack as unmodified, and the GC overhead + might be reduced. On the other hand, making stack chunks + too small adds some overhead as there will be more + overflow/underflow between chunks. The default setting of + 32k appears to be a reasonable compromise in most cases. + + + + + + + size + RTS + option + stackchunk buffer size + + + + [Default: 1k] Sets the stack chunk buffer size. + When a stack chunk overflows and a new stack chunk is + created, some of the data from the previous stack chunk is + moved into the new chunk, to avoid an immediate underflow + and repeated overflow/underflow at the boundary. The + amount of stack moved is set by the + option. + + + Note that to avoid wasting space, this value should + typically be less than 10% of the size of a stack + chunk (), because in a chain of stack + chunks, each chunk will have a gap of unused space of this + size. + + @@ -451,9 +518,14 @@ [Default: 8M] Set the maximum stack size for an individual thread to size - bytes. This option is there purely to stop the program - eating up all the available memory in the machine if it gets - into an infinite loop. + bytes. If the thread attempts to exceed this limit, it will + be send the StackOverflow exception. + + + This option is there mainly to stop the program eating up + all the available memory in the machine if it gets into an + infinite loop. + @@ -1089,7 +1161,8 @@ The hook ghc_rts_optsghc_rts_opts lets you set RTS - options permanently for a given program. A common use for this is + options permanently for a given program, in the same way as the + newer linker option does. A common use for this is to give your program a default heap and/or stack size that is greater than the default. For example, to set -H128m -K1m, place the following definition in a C source @@ -1295,7 +1368,6 @@ $ ./a.out +RTS --info