erl_set_memory_block(3erl)					C Library Functions					erl_set_memory_block(3erl)

NAME

       erl_set_memory_block - Custom memory allocation for Erlang on VxWorks(R)

DESCRIPTION

       This documentation is specific to VxWorks.

       The erl_set_memory_block 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.

       The memory within the block can be utilized by other tasks than Erlang. This is accomplished by calling the functions sys_alloc , sys_real-
       loc and sys_free instead of malloc , realloc and free respectively.

       The  purpose  of  this  is  to avoid problems inherent in the VxWorks systems malloc 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.

       The erl_set_memory_block function is callable from any C program as an ordinary 10 argument function as well as from the commandline.

EXPORTS

       int erl_set_memory_block(size_t size, void *ptr, int warn_mixed_malloc, int realloc_always_moves, int use_reclaim, ...)

	      The function is called before Erlang is started to specify a large memory block where Erlang can maintain memory internally.

	      Parameters:

		size_t size :
		  The size in bytes of Erlang's internal memory block. Has to be specified. Note that the VxWorks system uses dynamic memory allo-
		  cation heavily, so leave some memory to the system.

		void *ptr :
		  A pointer to the actual memory block of size size . 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.

		  If  a  memory  block	is  allocated and provided here, the sys_alloc 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 use_reclaim flag.

		  If  0  is  specified	here,  the  Erlang  system  should  not be stopped while some other task uses the memory block (has called
		  sys_alloc ).

		int warn_mixed_malloc :
		  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  mix-
		  ing normal malloc with sys_realloc or sys_free .

		int realloc_always_moves :
		  If this flag is set to true (anything else than 0), all calls to sys_realloc result in a moved memory block. This can in certain
		  conditions give less fragmentation. This flag may be removed in future releases.

		int use_reclaim :
		  If this flag is set to true (anything else than 0), all memory allocated with sys_alloc 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 save_open etc. specified in the reclaim.h file delivered in the Erlang distribution.

	      Return Value:

	      Returns 0 (OK) on success, otherwise a value <> 0.

       int erl_memory_show(...)

	      Return Value:

	      Returns 0 (OK) on success, otherwise a value <> 0.

       int erl_mem_info_get(MEM_PART_STATS *stats)

	      Parameter:

		MEM_PART_STATS *stats :
		  A pointer to a MEM_PART_STATS structure as defined in <memLib.h> . A successful call will fill in all fields of  the	structure,
		  on error all fields are left untouched.

	      Return Value:

	      Returns 0 (OK) on success, otherwise a value <> 0

NOTES

       The  memory  block  used  by  Erlang  actually  does  not  need	to be inside the area known to ordinary malloc . It is possible to set the
       USER_RESERVED_MEM preprocessor symbol when compiling the wind kernel and then use user reserved memory for Erlang. Erlang can therefor uti-
       lize memory above the 32 Mb limit of VxWorks on the PowerPC architecture.

       Example:

       In config.h for the wind kernel:

	     #undef LOCAL_MEM_AUTOSIZE
	     #undef LOCAL_MEM_SIZE
	     #undef USER_RESERVED_MEM

	     #define LOCAL_MEM_SIZE	   0x05000000
	     #define USER_RESERVED_MEM	   0x03000000

       In the start-up script/code for the VxWorks node:

       erl_set_memory_block(sysPhysMemTop()-sysMemTop(),sysMemTop(),0,0,1);

       Setting	the  use_reclaim 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 save_malloc , save_realloc and save_free  provide  the
       same facilities by using VxWorks own malloc . Similar routines exist for files, see the file reclaim.h in the distribution.

Ericsson AB							    erts 5.8.3						erl_set_memory_block(3erl)