newlib/winsup/doc/setup-maxmem.xml

67 lines
2.9 KiB
XML
Raw Normal View History

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>
<para>
Cygwin's heap is extensible. However, it does start out at a fixed size
and attempts to extend it may run into memory which has been previously
allocated by Windows. In some cases, this problem can be solved by
changing a field in the file header which is utilized by Cygwin since
version 1.7.10 to keep the initial size of the application heap. If the
field contains 0, which is the default, the application heap defaults to
a size of 384 Megabyte. If the field is set to any other value between 4 and
2048, Cygwin tries to reserve as much Megabytes for the application heap.
The field used for this is the "LoaderFlags" field in the NT-specific
PE header structure (<literal>(IMAGE_NT_HEADER)->OptionalHeader.LoaderFlags</literal>).</para>
<para>
This value can be changed for any executable by using a more recent version
of the <command>peflags</command> tool from the <literal>rebase</literal>
Cygwin package. Example:
<screen>
$ peflags --cygwin-heap foo.exe
foo.exe: initial Cygwin heap size: 0 (0x0) MB
$ peflags --cygwin-heap=500 foo.exe
foo.exe: initial Cygwin heap size: 500 (0x1f4) MB
</screen>
</para>
<para>
Heap memory can be allocated up to the size of the biggest available free
block in the processes virtual memory (VM). By default, the VM per process
is 2 GB for 32 processes. To get more VM for a process, the executable
must have the "large address aware" flag set in the file header. You can
use the aforementioned <command>peflags</command> tool to set this flag.
On 64 bit systems this results in a 4 GB VM for a process started from that
executable. On 32 bit systems you also have to prepare the system to allow
up to 3 GB per process. See the Microsoft article
<ulink url="http://msdn.microsoft.com/en-us/library/bb613473%28VS.85%29.aspx">4-Gigabyte Tuning</ulink>
for more information.
</para>
<note>
<para>
Older Cygwin releases only supported a global registry setting to
change the initial heap size for all Cygwin processes. This setting is
not used anymore. However, if you're running an older Cygwin release
than 1.7.10, you can add the <literal>DWORD</literal> value
<literal>heap_chunk_in_mb</literal> and set it to the desired memory limit
in decimal MB. You have to stop all Cygwin processes for this setting to
have any effect. It is preferred to do this in Cygwin using the
<command>regtool</command> program included in the Cygwin package.
(see <xref linkend="regtool"></xref>) This example sets the memory limit
to 1024 MB for all Cygwin processes (use HKCU instead of HKLM if you
want to set this only for the current user):
<screen>
$ regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
$ regtool -v list /HKLM/Software/Cygwin
</screen>
</para>
</note>
</sect1>