cpu_sup(3)



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, Linux and FreeBSD.

       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 displayed
       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  capac-
       ity,  then  this  way of measuring presents a problem, because the load
       values are not restricted to a fixed interval. In this case,  the  fol-
       lowing 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  percent-
       age.  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 re-
       quests, it will still score 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 termi-
       nate.

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 de-
              scribed above. 0 represents no load, 256 represents the load re-
              ported 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  de-
              scribed above. 0 represents no load, 256 represents the load re-
              ported 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  af-
              ter 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 af-
              ter 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  infor-
                  mation 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  oper-
              ating  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 pro-
              cessor 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.5.2                    cpu_sup(3erl)

Man(1) output converted with man2html
list of all man pages