memsup(3erl)						     Erlang Module Definition						      memsup(3erl)

NAME

       memsup - A Memory Supervisor Process

DESCRIPTION

       memsup  is  a  process which supervises the memory usage for the system and for individual processes. It is part of the OS_Mon application,
       see os_mon(7) . Available for Unix, Windows and VxWorks.

       Periodically performs a memory check:

	 * If more than a certain amount of available system memory is allocated, as reported by the underlying operating system, the alarm  {sys-
	   tem_memory_high_watermark, []} is set.

	 * If  any  Erlang  process  Pid  in  the  system has allocated more than a certain amount of total system memory, the alarm {process_mem-
	   ory_high_watermark, Pid} is set.

       Alarms are reported to the SASL alarm handler, see alarm_handler(3erl) . 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 function get_memory_data() can be used to retrieve the result of the latest periodic memory check.

       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.

       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.

CONFIGURATION

       The following configuration parameters can be used to change the default values for time intervals and thresholds:

	 memory_check_interval = int()>0 :
	   The time interval, in minutes, for the periodic memory check. The default is one minute.

	 system_memory_high_watermark = float() :
	   The threshold, as percentage of system memory, for how much system memory can be allocated before the corresponding alarm is  set.  The
	   default is 0.80 (80%).

	 process_memory_high_watermark = float() :
	   The threshold, as percentage of system memory, for how much system memory can be allocated by one Erlang process before the correspond-
	   ing alarm is set. The default is 0.05 (5%).

	 memsup_helper_timeout = int()>0 :
	   A timeout, in seconds, for how long the memsup process should wait for a result from a memory check. If the timeout expires, a  warning
	   message  "OS_MON (memsup) timeout" is issued via error_logger and any pending, synchronous client calls will return a dummy value. Nor-
	   mally, this situation should not occur. There have 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 default is 30 seconds.

	 memsup_system_only = bool() :
	   Specifies  whether the memsup process should only check system memory usage ( true ) or not. The default is false , meaning that infor-
	   mation regarding both system memory usage and Erlang process memory usage is collected.

	   It is recommended to set this parameter to false on systems with many concurrent processes, as each process memory check makes  a  tra-
	   versal of the entire list of processes.

       See config(5) for information about how to change the value of configuration parameters.

EXPORTS

       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.

	      Returns {0,0,{pid(),0}} or {0,0,undefined} if memsup is not available, or if all memory checks so far have timed out.

       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.

		buffered_memory :
		  The amount of memory the system uses for temporary storing raw disk blocks.

		cached_memory :
		  The amount of memory the system uses for cached files read from disk.

		total_swap :
		  The amount of total amount of memory the system has available for disk swap.

		free_swap :
		  The amount of memory the system has available for disk swap.

	      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.

	      Returns the empty list [] if memsup is not available, or if the memory check times out.

   Note:
       On linux the memory available to the emulator is cached_memory and buffered_memory in addition to free_memory .

       get_os_wordsize() -> Wordsize

	      Types  Wordsize = 32 | 64 | unsupported_os

	      Returns the wordsize of the current running operating system.

       get_check_interval() -> MS

	      Types  MS = int()

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

       set_check_interval(Minutes) -> ok

	      Types  Minutes = int()>0

	      Changes the time interval, given in minutes, for the periodic memory check.

	      The  change will take effect after the next memory check and is non-persistent. That is, in case of a process restart, this value is
	      forgotten and the default value will be used. See Configuration above.

       get_procmem_high_watermark() -> int()

	      Returns the threshold, in percent, for process memory allocation.

       set_procmem_high_watermark(Float) -> ok

	      Changes the threshold, given as a float, for process memory allocation.

	      The change will take effect during the next periodic memory check and is non-persistent. That is, in case of a process restart, this
	      value is forgotten and the default value will be used. See Configuration above.

       get_sysmem_high_watermark() -> int()

	      Returns the threshold, in percent, for system memory allocation.

       set_sysmem_high_watermark(Float) -> ok

	      Changes the threshold, given as a float, for system memory allocation.

	      The change will take effect during the next periodic memory check and is non-persistent. That is, in case of a process restart, this
	      value is forgotten and the default value will be used. See Configuration above.

       get_helper_timeout() -> Seconds

	      Types  Seconds = int()

	      Returns the timeout value, in seconds, for memory checks.

       set_helper_timeout(Seconds) -> ok

	      Types  Seconds = int() (>= 1)

	      Changes the timeout value, given in seconds, for memory checks.

	      The change will take effect for the next memory check and is non-persistent. That is, in the case of a process restart,  this  value
	      is forgotten and the default value will be used. See Configuration above.

SEE ALSO

       alarm_handler(3erl) , os_mon(3erl)

Ericsson AB							   os_mon 2.2.5 						      memsup(3erl)