1Function: allocatemem
2Section: programming/specific
3C-Name: gp_allocatemem
4Prototype: vDG
5Help: allocatemem({s=0}): allocates a new stack of s bytes. doubles the
6 stack if s is omitted.
7Doc: this special operation changes the stack size \emph{after}
8 initialization. The argument $s$ must be a nonnegative integer.
9 If $s > 0$, a new stack of at least $s$ bytes is allocated. We may allocate
10 more than $s$ bytes if $s$ is way too small, or for alignment reasons: the
11 current formula is $\max(16*\ceil{s/16}, 500032)$ bytes.
12
13 If $s=0$, the size of the new stack is twice the size of the old one.
14
15 This command is much more useful if \tet{parisizemax} is nonzero, and we
16 describe this case first. With \kbd{parisizemax} enabled, there are three
17 sizes of interest:
18
19 \item a virtual stack size, \tet{parisizemax}, which is an absolute upper
20 limit for the stack size; this is set by \kbd{default(parisizemax, ...)}.
21
22 \item the desired typical stack size, \tet{parisize}, that will grow as
23 needed, up to \tet{parisizemax}; this is set by \kbd{default(parisize, ...)}.
24
25 \item the current stack size, which is less that \kbd{parisizemax},
26 typically equal to \kbd{parisize} but possibly larger and increasing
27 dynamically as needed; \kbd{allocatemem} allows to change that one
28 explicitly.
29
30 The \kbd{allocatemem} command forces stack
31 usage to increase temporarily (up to \kbd{parisizemax} of course); for
32 instance if you notice using \kbd{\bs gm2} that we seem to collect garbage a
33 lot, e.g.
34 \bprog
35 ? \gm2
36   debugmem = 2
37 ? default(parisize,"32M")
38  ***   Warning: new stack size = 32000000 (30.518 Mbytes).
39 ? bnfinit('x^2+10^30-1)
40  *** bnfinit: collecting garbage in hnffinal, i = 1.
41  *** bnfinit: collecting garbage in hnffinal, i = 2.
42  *** bnfinit: collecting garbage in hnffinal, i = 3.
43 @eprog\noindent and so on for hundred of lines. Then, provided the
44 \tet{breakloop} default is set, you can interrupt the computation, type
45 \kbd{allocatemem(100*10\pow6)} at the break loop prompt, then let the
46 computation go on by typing \kbd{<Enter>}. Back at the \kbd{gp} prompt,
47 the desired stack size of \kbd{parisize} is restored. Note that changing either
48 \kbd{parisize} or \kbd{parisizemax} at the break loop prompt would interrupt
49 the computation, contrary to the above.
50
51 In most cases, \kbd{parisize} will increase automatically (up to
52 \kbd{parisizemax}) and there is no need to perform the above maneuvers.
53 But that the garbage collector is sufficiently efficient that
54 a given computation can still run without increasing the stack size,
55 albeit very slowly due to the frequent garbage collections.
56
57 \misctitle{Deprecated: when \kbd{parisizemax} is unset}
58 This is currently still the default behavior in order not to break backward
59 compatibility. The rest of this section documents the
60 behavior of \kbd{allocatemem} in that (deprecated) situation: it becomes a
61 synonym for \kbd{default(parisize,...)}. In that case, there is no
62 notion of a virtual stack, and the stack size is always equal to
63 \kbd{parisize}. If more memory is needed, the PARI stack overflows, aborting
64 the computation.
65
66 Thus, increasing \kbd{parisize} via \kbd{allocatemem} or
67 \kbd{default(parisize,...)} before a big computation is important.
68 Unfortunately, either must be typed at the \kbd{gp} prompt in
69 interactive usage, or left by itself at the start of batch files.
70 They cannot be used meaningfully in loop-like constructs, or as part of a
71 larger expression sequence, e.g
72 \bprog
73    allocatemem(); x = 1;   \\@com This will not set \kbd{x}!
74 @eprog\noindent
75 In fact, all loops are immediately exited, user functions terminated, and
76 the rest of the sequence following \kbd{allocatemem()} is silently
77 discarded, as well as all pending sequences of instructions. We just go on
78 reading the next instruction sequence from the file we are in (or from the
79 user). In particular, we have the following possibly unexpected behavior: in
80 \bprog
81    read("file.gp"); x = 1
82 @eprog\noindent were \kbd{file.gp} contains an \kbd{allocatemem} statement,
83 the \kbd{x = 1} is never executed, since all pending instructions in the
84 current sequence are discarded.
85
86 The reason for these unfortunate side-effects is that, with
87 \kbd{parisizemax} disabled, increasing the stack size physically
88 moves the stack, so temporary objects created during the current expression
89 evaluation are not correct anymore. (In particular byte-compiled expressions,
90 which are allocated on the stack.) To avoid accessing obsolete pointers to
91 the old stack, this routine ends by a \kbd{longjmp}.
92