diff options
Diffstat (limited to 'lib/sasl/doc/src/overload.xml')
| -rw-r--r-- | lib/sasl/doc/src/overload.xml | 124 |
1 files changed, 59 insertions, 65 deletions
diff --git a/lib/sasl/doc/src/overload.xml b/lib/sasl/doc/src/overload.xml index 35877220ab..5c3d00afeb 100644 --- a/lib/sasl/doc/src/overload.xml +++ b/lib/sasl/doc/src/overload.xml @@ -35,98 +35,88 @@ <module>overload</module> <modulesummary>An Overload Regulation Process</modulesummary> <description> - <p><c>overload</c> is a process which indirectly regulates CPU + <p><c>overload</c> is a process that indirectly regulates the CPU usage in the system. The idea is that a main application calls - the <c>request/0</c> function before starting a major job, and + 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, the <c>MaxIntensity</c> - and the <c>Weight</c> value (both are measured in 1/second). - </p> + 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> + <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 total intensity. - </p> + <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 accept intensity, - provided that 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> + <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 will react to + speed with which the calculations of intensities react to changes in the underlying input intensity. The inverted value of - <c>Weight</c>, - </p> - <p><c>T = 1/Weight</c></p> - <p>can be thought of as the "time constant" - of the intensity calculation formulas. For example, if <c>Weight = 0.1</c>, then a change in the underlying input intensity will be - reflected in the <c>total</c> and <c>accept intensities</c> within - approximately 10 seconds. - </p> + <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: - </p> + <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 accept intensity exceeds - <c>MaxIntensity</c>. - </p> + <p>This alarm is set when the current <c>accept intensity</c> exceeds + <c>MaxIntensity</c>.</p> </item> </taglist> - <p>A new overload alarm is not set until the current accept - intensity has fallen below <c>MaxIntensity</c>. To prevent the - overload process from generating a lot of set/reset alarms, the - alarm is not reset until the current accept intensity has fallen - below 75% of <c>MaxIntensity</c>, and it is not until then that - the alarm can be set again. - </p> + <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>Request to proceed with current job</fsummary> + <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 accept intensity. </p> + current value of the <c>accept intensity</c>.</p> <p>The application - calling this function should be processed with the job in + calling this function is to proceed with the job in question if the return value is <c>accept</c>; otherwise it - should not continue with that job. - </p> + is not to continue with that job.</p> </desc> </func> + <func> <name>get_overload_info() -> OverloadInfo</name> - <fsummary>Return current overload information data</fsummary> + <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>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> @@ -135,18 +125,22 @@ <v>AcceptedRequests = integer()</v> </type> <desc> - <p>Returns the current total and accept intensities, the - configuration parameters, and absolute counts of the total - number of requests, and accepted number of requests (since - the overload process was started).</p> + <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>alarm_handler(3), sasl(3) - </p> + <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>, + <seealso marker="sasl_app"><c>sasl(6)</c></seealso></p> </section> </erlref> |