diff options
Diffstat (limited to 'erts/doc/src/erl_set_memory_block.xml')
| -rw-r--r-- | erts/doc/src/erl_set_memory_block.xml | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/erts/doc/src/erl_set_memory_block.xml b/erts/doc/src/erl_set_memory_block.xml new file mode 100644 index 0000000000..d77da56d95 --- /dev/null +++ b/erts/doc/src/erl_set_memory_block.xml @@ -0,0 +1,172 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> + +<cref> + <header> + <copyright> + <year>1998</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>erl_set_memory_block</title> + <prepared>Patrik Nyblom</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>98-08-05</date> + <rev>A</rev> + <file>erl_set_memory_block.xml</file> + </header> + <lib>erl_set_memory_block</lib> + <libsummary>Custom memory allocation for Erlang on VxWorks®</libsummary> + <description> + <p>This documentation is specific to VxWorks.</p> + <p>The <c><![CDATA[erl_set_memory_block]]></c> function/command initiates custom + memory allocation for the Erlang emulator. It has to be called + before the Erlang emulator is started and makes Erlang use one + single large memory block for all memory allocation.</p> + <p>The memory within the block can be utilized by other tasks than + Erlang. This is accomplished by calling the functions + <c><![CDATA[sys_alloc]]></c>, <c><![CDATA[sys_realloc]]></c> and <c><![CDATA[sys_free]]></c> instead + of <c><![CDATA[malloc]]></c>, <c><![CDATA[realloc]]></c> and <c><![CDATA[free]]></c> respectively.</p> + <p>The purpose of this is to avoid problems inherent in the + VxWorks systems <c><![CDATA[malloc]]></c> library. The memory allocation within the + large memory block avoids fragmentation by using an "address + order first fit" algorithm. Another advantage of using a + separate memory block is that resource reclamation can be made + more easily when Erlang is stopped.</p> + <p>The <c><![CDATA[erl_set_memory_block]]></c> function is callable from any C + program as an ordinary 10 argument function as well as + from the commandline.</p> + </description> + <funcs> + <func> + <name><ret>int</ret><nametext>erl_set_memory_block(size_t size, void *ptr, int warn_mixed_malloc, int realloc_always_moves, int use_reclaim, ...)</nametext></name> + <fsummary>Specify parameters for Erlang internal memory allocation.</fsummary> + <desc> + <p>The function is called before Erlang is + started to specify a large memory block where Erlang can + maintain memory internally.</p> + <p>Parameters:</p> + <taglist> + <tag>size_t size</tag> + <item>The size in bytes of Erlang's internal memory block. Has to + be specified. Note that the VxWorks system uses dynamic + memory allocation heavily, so leave some memory to the system.</item> + <tag>void *ptr</tag> + <item> + <p>A pointer to the actual memory block of size + <c><![CDATA[size]]></c>. If this is specified as 0 (NULL), Erlang will + allocate the memory when starting and will reclaim the + memory block (as a whole) when stopped.</p> + <p>If a memory block is allocated and provided here, the + <c><![CDATA[sys_alloc]]></c> etc routines can still be used after + the Erlang emulator is stopped. The Erlang emulator can + also be restarted while other tasks using the memory + block are running without destroying the memory. If + Erlang is to be restarted, also set the + <c><![CDATA[use_reclaim]]></c> flag.</p> + <p>If 0 is specified here, the Erlang system should not + be stopped while some other task uses the memory block + (has called <c><![CDATA[sys_alloc]]></c>).</p> + </item> + <tag>int warn_mixed_malloc</tag> + <item> + <p>If this flag is set to true (anything else than 0), the + system will write a warning message on the console if a + program is mixing normal <c><![CDATA[malloc]]></c> with + <c><![CDATA[sys_realloc]]></c> or <c><![CDATA[sys_free]]></c>.</p> + </item> + <tag>int realloc_always_moves</tag> + <item> + <p>If this flag is set to true (anything else than 0), all + calls to <c><![CDATA[sys_realloc]]></c> result in a moved memory + block. This can in certain conditions give less + fragmentation. This flag may be removed in future releases.</p> + </item> + <tag>int use_reclaim</tag> + <item> + <p>If this flag is set to true (anything else than 0), all + memory allocated with <c><![CDATA[sys_alloc]]></c> is automatically + reclaimed as soon as a task exits. This is very useful + to make writing port programs (and other programs as + well) easier. Combine this with using the routines + <c><![CDATA[save_open]]></c> etc. specified in the reclaim.h + file delivered in the Erlang distribution.</p> + </item> + </taglist> + <p>Return Value:</p> + <p>Returns 0 (OK) on success, otherwise a value <> 0.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_memory_show(...)</nametext></name> + <fsummary>A utility similar to VxWorks <c><![CDATA[memShow]]></c>, but for the Erlang memory area.</fsummary> + <desc> + <p>Return Value:</p> + <p>Returns 0 (OK) on success, otherwise a value <> 0.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>erl_mem_info_get(MEM_PART_STATS *stats)</nametext></name> + <fsummary>A utility similar to VxWorks <c><![CDATA[memPartInfoGet]]></c>, but for the Erlang memory area.</fsummary> + <desc> + <p>Parameter:</p> + <taglist> + <tag>MEM_PART_STATS *stats</tag> + <item>A pointer to a MEM_PART_STATS structure as defined in + <c><![CDATA[<memLib.h>]]></c>. A successful call will fill in all + fields of the structure, on error all fields are left untouched. </item> + </taglist> + <p>Return Value:</p> + <p>Returns 0 (OK) on success, otherwise a value <> 0</p> + </desc> + </func> + </funcs> + + <section> + <title>NOTES</title> + <p>The memory block used by Erlang actually does not need to be + inside the area known to ordinary <c><![CDATA[malloc]]></c>. It is possible + to set the <c><![CDATA[USER_RESERVED_MEM]]></c> preprocessor symbol when compiling + the wind kernel and then use user reserved memory for + Erlang. Erlang can therefor utilize memory above the 32 Mb limit + of VxWorks on the PowerPC architecture.</p> + <p>Example:</p> + <p>In config.h for the wind kernel:</p> + <code type="none"><![CDATA[ + #undef LOCAL_MEM_AUTOSIZE + #undef LOCAL_MEM_SIZE + #undef USER_RESERVED_MEM + + #define LOCAL_MEM_SIZE 0x05000000 + #define USER_RESERVED_MEM 0x03000000 + ]]></code> + <p>In the start-up script/code for the VxWorks node:</p> + <code type="none"><![CDATA[ +erl_set_memory_block(sysPhysMemTop()-sysMemTop(),sysMemTop(),0,0,1); + ]]></code> + <p>Setting the <c><![CDATA[use_reclaim]]></c> flag decreases performance of the + system, but makes programming much easier. Other similar + facilities are present in the Erlang system even without using a + separate memory block. The routines called <c><![CDATA[save_malloc]]></c>, + <c><![CDATA[save_realloc]]></c> and <c><![CDATA[save_free]]></c> provide the same + facilities by using VxWorks own <c><![CDATA[malloc]]></c>. Similar routines + exist for files, see the file <c><![CDATA[reclaim.h]]></c> in the distribution.</p> + </section> +</cref> + |