cpu_sup(3erl)						     Erlang Module Definition						     cpu_sup(3erl)

NAME

       cpu_sup - A CPU Load and CPU Utilization Supervisor Process

DESCRIPTION

       cpu_sup is a process which supervises the CPU load and CPU utilization. It is part of the OS_Mon application, see os_mon(7) . Available for
       Unix, although CPU utilization values ( util/0,1 ) are only available for Solaris and Linux.

       The load values are proportional to how long time a runnable Unix process has to spend in the run queue before  it  is  scheduled.  Accord-
       ingly,  higher  values mean more system load. The returned value divided by 256 produces the figure displayed by rup and top . What is dis-
       played as 2.00 in rup , is displayed as load up to the second mark in xload .

       For example, rup displays a load of 128 as 0.50, and 512 as 2.00.

       If the user wants to view load values as percentage of machine capacity, then this way of measuring presents a problem,	because  the  load
       values are not restricted to a fixed interval. In this case, the following simple mathematical transformation can produce the load value as
       a percentage:

	     PercentLoad = 100 * (1 - D/(D + Load))

       D determines which load value should be associated with which percentage. Choosing D = 50 means that 128 is 60% load, 256 is  80%,  512	is
       90%, and so on.

       Another	way of measuring system load is to divide the number of busy CPU cycles by the total number of CPU cycles. This produces values in
       the 0-100 range immediately. However, this method hides the fact that a machine can be more or less saturated. CPU utilization is therefore
       a better name than system load for this measure.

       A  server  which  receives  just enough requests to never become idle will score a CPU utilization of 100%. If the server receives 50% more
       requests, it will still scores 100%. When the system load is calculated with  the  percentage  formula  shown  previously,  the	load  will
       increase from 80% to 87%.

       The  avg1/0 , avg5/0 , and avg15/0 functions can be used for retrieving system load values, and the util/0 and util/1 functions can be used
       for retrieving CPU utilization values.

       When run on Linux, cpu_sup assumes that the /proc file system is present and accessible by cpu_sup . If it is not, cpu_sup will terminate.

EXPORTS

       nprocs() -> UnixProcesses | {error, Reason}

	      Types  UnixProcesses = int()
		     Reason = term()

	      Returns the number of UNIX processes running on this machine. This is a crude way of measuring the system load, but  it  may  be	of
	      interest in some cases.

	      Returns 0 if cpu_sup is not available.

       avg1() -> SystemLoad | {error, Reason}

	      Types  SystemLoad = int()
		     Reason = term()

	      Returns  the  average  system load in the last minute, as described above. 0 represents no load, 256 represents the load reported as
	      1.00 by rup .

	      Returns 0 if cpu_sup is not available.

       avg5() -> SystemLoad | {error, Reason}

	      Types  SystemLoad = int()
		     Reason = term()

	      Returns the average system load in the last five minutes, as described above. 0 represents no load, 256 represents the load reported
	      as 1.00 by rup .

	      Returns 0 if cpu_sup is not available.

       avg15() -> SystemLoad | {error, Reason}

	      Types  SystemLoad = int()
		     Reason = term()

	      Returns  the  average system load in the last 15 minutes, as described above. 0 represents no load, 256 represents the load reported
	      as 1.00 by rup .

	      Returns 0 if cpu_sup is not available.

       util() -> CpuUtil | {error, Reason}

	      Types  CpuUtil = float()
		     Reason = term()

	      Returns CPU utilization since the last call to util/0 or util/1 by the calling process.

   Note:
       The returned value of the first call to util/0 or util/1 by a process will on most systems be the CPU utilization since	system	boot,  but
       this  is  not  guaranteed  and  the  value  should therefore be regarded as garbage. This also applies to the first call after a restart of
       cpu_sup .

       The CPU utilization is defined as the sum of the percentage shares of the CPU cycles spent in all busy processor states (see util/1  below)
       in average on all CPUs.

       Returns 0 if cpu_sup is not available.

       util(Opts) -> UtilSpec | {error, Reason}

	      Types  Opts = [detailed | per_cpu]
		     UtilSpec = UtilDesc | [UtilDesc]
		     UtilDesc = {Cpus, Busy, NonBusy, Misc}
		     Cpus = all | int() | [int()]()
		     Busy = NonBusy = {State, Share} | Share
		     State = user | nice_user | kernel
		     | wait | idle | atom()
		     Share = float()
		     Misc = []
		     Reason = term()

	      Returns CPU utilization since the last call to util/0 or util/1 by the calling process, in more detail than util/0 .

   Note:
       The  returned  value  of the first call to util/0 or util/1 by a process will on most systems be the CPU utilization since system boot, but
       this is not guaranteed and the value should therefore be regarded as garbage. This also applies to  the	first  call  after  a  restart	of
       cpu_sup .

       Currently recognized options:

	 detailed :
	   The returned UtilDesc (s) will be even more detailed.

	 per_cpu :
	   Each  CPU will be specified separately (assuming this information can be retrieved from the operating system), that is, a list with one
	   UtilDesc per CPU will be returned.

       Description of UtilDesc = {Cpus, Busy, NonBusy, Misc} :

	 Cpus :
	   If the detailed and/or per_cpu option is given, this is the CPU number, or a list of the CPU numbers.

	   If not, this is the atom all which implies that the UtilDesc contains information about all CPUs.

	 Busy :
	   If the detailed option is given, this is a list of {State, Share} tuples, where each tuple contains information about a processor state
	   that has been identified as a busy processor state (see below). The atom State is the name of the state, and the float Share represents
	   the percentage share of the CPU cycles spent in this state since the last call to util/0 or util/1 .

	   If not, this is the sum of the percentage shares of the CPU cycles spent in all states identified as busy.

	   If the per_cpu is not given, the value(s) presented are the average of all CPUs.

	 NonBusy :
	   Similar to Busy , but for processor states that have been identified as non-busy (see below).

	 Misc :
	   Currently unused; reserved for future use.

       Currently these processor states are identified as busy:

	 user :
	   Executing code in user mode.

	 nice_user :
	   Executing code in low priority (nice) user mode. This state is currently only identified on Linux.

	 kernel :
	   Executing code in kernel mode.

       Currently these processor states are identified as non-busy:

	 wait :
	   Waiting. This state is currently only identified on Solaris.

	 idle :
	   Idle.

   Note:
       Identified processor states may be different on different operating systems and may change between different versions  of  cpu_sup  on  the
       same  operating	system. The sum of the percentage shares of the CPU cycles spent in all busy and all non-busy processor states will always
       add up to 100%, though.

       Returns {all,0,0,[]} if cpu_sup is not available.

SEE ALSO

       os_mon(3erl)

Ericsson AB							   os_mon 2.2.5 						     cpu_sup(3erl)