---
name: "erl_set_memory_block"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:15.b.1-dfsg-4+deb7u1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/erl_set_memory_block"
---

# erl\_set\_memory\_block(3erl)

Custom memory allocation for Erlang on VxWorks(R)

## 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\_realloc* 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

**interl\_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 allocation 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 mixing 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.

**interl\_memory\_show(...)**\

Return Value:

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

**interl\_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 utilize 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.