path: root/lib/sasl/doc/src/overload.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>overload</title>
    <prepared>Peter H&ouml;gfeldt</prepared>
    <responsible>Peter H&ouml;gfeldt</responsible>
    <docno></docno>
    <approved>(Joe Armstrong)</approved>
    <checked></checked>
    <date>1996-10-29</date>
    <rev>A</rev>
    <file>overload.sgml</file>
  </header>
  <module>overload</module>
  <modulesummary>An Overload Regulation Process</modulesummary>
  <description>
    <warning>
      <p>
	All functions in this module are deprecated and will be
	removed in a future release.
      </p>
    </warning>
    <p><c>overload</c> is a process that indirectly regulates the CPU
      usage in the system. The idea is that a main application calls
      function 
      <seealso marker="#request/0"><c>request/0</c></seealso> 
      before starting a major job and
      proceeds with the job if the return value is positive; otherwise
      the job must not be started.</p>
    <p><c>overload</c> is part of the <c>SASL</c> application and all
      configuration parameters are defined there.</p>
    <p>A set of two intensities are maintained, the <c>total intensity</c>
      and the <c>accept intensity</c>. For that purpose,
      there are two configuration parameters, <c>MaxIntensity</c>
      and <c>Weight</c>; both are measured in 1/second.</p>
    <p>Then total and accept intensities are calculated as
      follows. Assume that the time of the current call to
      <c>request/0</c> is <c>T(n)</c> and that the time of the
      previous call was <c>T(n-1)</c>.</p>
    <list type="bulleted">
      <item>
        <p>The current <c>total intensity</c>, denoted
          <c>TI(n)</c>, is calculated according to the formula</p>
        <p><c>TI(n) = exp(-Weight*(T(n) - T(n-1)) * TI(n-1) +  Weight</c>,</p>
        <p>where <c>TI(n-1)</c> is the previous <c>total intensity</c>.</p>
      </item>
      <item>
        <p>The current <c>accept intensity</c>, denoted
          <c>AI(n)</c>, is determined by the formula</p>
        <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + Weight</c>,</p>
        <p>where <c>AI(n-1)</c> is the previous <c>accept intensity</c>,
          if the value of <c>exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c>
          is less than <c>MaxIntensity</c>. Otherwise the value is</p>
        <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c></p>
      </item>
    </list>
    <p>The value of configuration parameter <c>Weight</c> controls the
      speed with which the calculations of intensities react to
      changes in the underlying input intensity. The inverted value of
      <c>Weight</c>, <c>T = 1/Weight</c>, can be thought of as the
      "time constant" of the intensity calculation formulas. For example,
      if <c>Weight = 0.1</c>, a change in the underlying input intensity is
      reflected in <c>total intensity</c> and <c>accept intensity</c> within
      about 10 seconds.</p>
    <p>The overload process defines one alarm, which it sets using
      <c>alarm_handler:set_alarm(Alarm)</c>. <c>Alarm</c> is defined
      as follows:</p>
    <taglist>
      <tag><c>{overload, []}</c></tag>
      <item>
        <p>This alarm is set when the current <c>accept intensity</c> exceeds
          <c>MaxIntensity</c>.</p>
      </item>
    </taglist>
    <p>A new request is not accepted until the current <c>accept
      intensity</c> has fallen below <c>MaxIntensity</c>. To prevent the
      overload process from generating many set/reset alarms, the
      alarm is not reset until the current <c>accept intensity</c> has fallen
      below 75% of <c>MaxIntensity</c>; it is not until then that
      the alarm can be set again.</p>
  </description>

  <funcs>
    <func>
      <name>request() -> accept | reject</name>
      <fsummary>Requests to proceed with current job.</fsummary>
      <desc>
        <p>Returns <c>accept</c> or <c>reject</c> depending on the
          current value of the <c>accept intensity</c>.</p>
        <p>The application
          calling this function is to proceed with the job in
          question if the return value is <c>accept</c>; otherwise it
          is not to continue with that job.</p>
      </desc>
    </func>

    <func>
      <name>get_overload_info() -> OverloadInfo</name>
      <fsummary>Returns current overload information data.</fsummary>
      <type>
        <v>OverloadInfo = [{total_intensity, TotalIntensity},
          {accept_intensity, AcceptIntensity}, {max_intensity,
          MaxIntensity}, {weight, Weight}, {total_requests,
          TotalRequests}, {accepted_requests, AcceptedRequests}].</v>
        <v>TotalIntensity = float() > 0</v>
        <v>AcceptIntensity = float() > 0</v>
        <v>MaxIntensity = float() > 0</v>
        <v>Weight = float() > 0</v>
        <v>TotalRequests = integer()</v>
        <v>AcceptedRequests = integer()</v>
      </type>
      <desc>
        <p>Returns:</p>
        <list type="bulleted">
          <item>Current total and accept intensities</item>
          <item>Configuration parameters</item>
          <item>Absolute counts of the total number of requests</item>
          <item>Accepted number of requests (since the overload
            process was started)</item>
        </list>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>,
      <seealso marker="sasl_app"><c>sasl(6)</c></seealso></p>
  </section>
</erlref>