memsup(3)

MODULE
memsup - A Memory Supervisor Process

DESCRIPTION

memsup is part of the OS_Mon application and all configuration parameters are defined in os_mon(3). Note: The parameters are read only when the process is started, which means changing a parameter value during normal operation has no effect.

memsup is a process which supervises the memory usage for the system and for individual processes, as follows:

    *   If more than system_memory_high_watermark of available system memory is allocated, as reported by the underlying operating system, the alarm {system_memory_high_watermark, []} is set.

    *   If any Erlang process Pid in the system has allocated more than process_memory_high_watermark of total system memory, the alarm {process_memory_high_watermark, Pid} is set.

Alarms are reported to the SASL alarm handler, see alarm_handler(3). To set an alarm, alarm_handler:set_alarm(Alarm) is called where Alarm is either of the alarms specified above.

The alarms are cleared automatically when the alarm cause is no longer valid.

The process performs a periodic memory check. Use get_memory_data() to retrieve the result.

There is also a interface to system dependent memory data, get_system_memory_data(). The result is highly dependent on the underlying operating system and the interface is targeted primarily for systems without virtual memory (e.g. VxWorks). The output on other systems is however still valid, although sparse.

A call to get_system_memory_data/0 is more costly than a call to get_memory_data/0 as data is collected synchronously when this function is called.

If a memory check (periodic or synchrous) times out for some reason, a warning message "OS_MON (memsup) timeout" is printed by error_loger. Normally, this should not occur. There has been cases on Linux, however, where the pseudo file from which system data is read is temporarily unavailable when the system is heavily loaded.

The total system memory reported under UNIX is the number of physical pages of memory times the page size, and the available memory is the number of available physical pages times the page size. This is a reasonable measure as swapping should be avoided anyway, but the task of defining total memory and available memory is difficult because of virtual memory and swapping.

EXPORTS

get_check_interval() -> Time

    Types
        Time = int()

    Returns the time interval, in milliseconds, for the periodic memory check.

    Defaults to 60000 ms = 1 minute. Can be configured by the configuration parameter memory_check_interval (which should be given in minutes, however).

get_memory_data() -> {Total,Allocated,Worst}

    Types
        Total = Allocated = int()
        Worst = {Pid, PidAllocated} | undefined
        Pid = pid()
        PidAllocated = int()

    Returns the result of the latest memory check, where Total is the total memory size and Allocated the allocated memory size, in bytes.

    Worst is the pid and number of allocated bytes of the largest Erlang process on the node. If memsup should not collect process data, that is if the configuration parameter memsup_system_only was set to true, Worst is undefined.

    The function is normally asynchronous in the sense that it does not invoke a memory check, but returns the latest available value. The one exception if is the function is called before a first memory check is finished, in which case it does not return a value until the memory check is finished. If the first memory check (or memory checks) time out, a dummy value is returned: {0, 0, {self(), 0}} or {0, 0, undefined}.

get_system_memory_data() -> MemDataList

    Types
        MemDataList = [{Tag, Size}]
        Tag = atom()
        Size = int()

    Invokes a memory check and returns the resulting, system dependent, data as a list of tagged tuples, where Tag can be one of the following:

        total_memory:
            The total amount of memory available to the Erlang emulator, allocated and free. May or may not be equal to the amount of memory configured in the system.

        free_memory:
            The amount of free memory available to the Erlang emulator for allocation.

        system_total_memory:
            The amount of memory available to the whole operating system. This may well be equal to total_memory but not necessarily.

        largest_free:
            The size of the largest contiguous free memory block available to the Erlang emulator.

        number_of_free:
            The number of free blocks available to the Erlang runtime system. This gives a fair indication of how fragmented the memory is.

    All memory sizes are presented as number of bytes.

    The largest_free and number_of_free tags are currently only returned on a VxWorks system.

    If the memory check times out, the empty list [] is returned.

get_procmem_high_watermark() -> int()

    Threshold as a percentage of the total available system memory. It specifies how much memory can be allocated by one Erlang process before the alarm is set.

    Defaults to 5%. Can be configure by the configuration parameter process_memory_high_watermark (which should be given as a float, however).

get_sysmem_high_watermark() -> int()

    Threshold as a percentage of the total available system memory. It specifies how much system memory can be allocated before the alarm is set.

    Defaults to 80%. Can be configured by the configuration parameter system_memory_high_watermark (which should be given as a float, however).

get_helper_timeout() -> Seconds

    Types
        Seconds = int()

    Returns the timeout value in seconds for memory checks, that is, how long to wait for a memory check to finish. If a memory check times out, a warning message is printed and any call to get_system_memory_data() will return a dummy value.

    Defaults to 30 s. The initial value can be configured by the configuration parameter memsup_helper_timeout.

set_helper_timeout(Seconds) -> ok

    Types
        Seconds = int() (>= 1)

    Changes the timeout value for memory checks.

    Failure: badarg if Seconds is not an integer or is an integer less than 1.

See Also

alarm_handler(3), os_mon(3)

AUTHORS
Martin Björklund - support@erlang.ericsson.se
Peter Högfeldt - support@erlang.ericsson.se
Patrik Nyblom - support@erlang.ericsson.se