From bef563618b7cb8a212ee18224c98e8868731091a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Fri, 9 Mar 2012 17:53:22 +0100 Subject: doc: Reintegrate R15B01 scheduler_wall_time doc --- erts/doc/src/erlang.xml | 116 ++++++++++++++++++++++++++++++++---------- erts/preloaded/src/erlang.erl | 9 ++-- 2 files changed, 94 insertions(+), 31 deletions(-) (limited to 'erts') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 4672c91a8f..30e3b02a0a 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4352,11 +4352,12 @@ true Information about exact reductions -

- NOTE: statistics(exact_reductions) is - a more expensive operation than - statistics(reductions) - especially on an Erlang machine with SMP support.

+ +

statistics(exact_reductions) is + a more expensive operation than + statistics(reductions) + especially on an Erlang machine with SMP support.

+ @@ -4364,6 +4365,10 @@ true Information about garbage collection

This information may not be valid for all implementations.

+ 
+> statistics(garbage_collection).
+{85,23961,0}
+
 @@ -4379,12 +4384,18 @@ true Information about reductions -

- NOTE: From erts version 5.5 (OTP release R11B) - this value does not include reductions performed in current - time slices of currently scheduled processes. If an - exact value is wanted, use - statistics(exact_reductions).

+ + +

Since erts-5.5 (OTP release R11B) + this value does not include reductions performed in current + time slices of currently scheduled processes. If an + exact value is wanted, use + statistics(exact_reductions).

+ + 
+> statistics(reductions).
+{2046,11}
+
 @@ -4402,25 +4413,78 @@ true

Note that the run-time is the sum of the run-time for all threads in the Erlang run-time system and may therefore be greater than the wall-clock time.

+ 
+> statistics(runtime).
+{1690,1620}
+
 Information about each schedulers work time -

- Returns time lapsed (Scheduler_Total_Time) and time spent working - (Scheduler_Worked_Time) for each scheduler since - the system flag scheduler_wall_time - was set to true.

-

- Returns undefined if the system flag - scheduler_wall_time is set to false. -

-

The list of scheduler information is unsorted and may come in different order - between calls. The time unit is undefined and may be changed and should only be used - to calculate relative utilization. -

+ +

+ Returns a list of tuples with {SchedulerId, + ActiveTime, TotalTime}, where + SchedulerId is an integer id of the scheduler, ActiveTime is + the duration the scheduler has been busy, TotalTime is the total time duration since + scheduler_wall_time + activation. The time unit is not defined and may be subject to change + between releases, operating systems and system restarts. + scheduler_wall_time should only be used to calculate relative + values for scheduler-utilization. ActiveTime can never exceed TotalTime. +

+ +

The definition of a busy scheduler is when it is not idle or not + scheduling (selecting) a process or port, meaning; executing process + code, executing linked-in-driver or NIF code, executing + built-in-functions or any other runtime handling, garbage collecting + or handling any other memory management. Note, a scheduler may also be + busy even if the operating system has scheduled out the scheduler + thread. +

+ +

+ Returns undefined if the system flag + scheduler_wall_time + is turned off. +

+ +

The list of scheduler information is unsorted and may appear in different order + between calls. +

+

Using scheduler_wall_time to calculate scheduler utilization.

+
+> erlang:system_flag(scheduler_wall_time, true).
+false
+> Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
+ok
+
+

Some time later we will take another snapshot and calculate scheduler-utilization per scheduler.

+
+> Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
+ok
+> lists:map(fun({{I, A0, T0}, {I, A1, T1}}) ->
+	{I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
+[{1,0.9743474730177548},
+ {2,0.9744843782751444},
+ {3,0.9995902361669045},
+ {4,0.9738012596572161},
+ {5,0.9717956667018103},
+ {6,0.9739235846420741},
+ {7,0.973237033077876},
+ {8,0.9741297293248656}]
+
+

Using the same snapshots to calculate a total scheduler-utilization.

+
+> {A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) ->
+	{Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), A/T.
+0.9769136803764825
+
+ +

scheduler_wall_time is by default disabled. Use erlang:system_flag(scheduler_wall_time, true) to enable it.

+ @@ -4445,8 +4509,8 @@ true

A process can be suspended by multiple processes and can be suspended multiple times by a single process. A suspended process will not leave the suspended state until its suspend - count reach zero. The suspend count of Suspendee is - decreased when + count reach zero. The suspend count of Suspendee + is decreased when erlang:resume_process(Suspendee) is called by the same process that called erlang:suspend_process(Suspendee). All increased suspend diff --git a/erts/preloaded/src/erlang.erl b/erts/preloaded/src/erlang.erl index 01173ce4d6..5e451c015b 100644 --- a/erts/preloaded/src/erlang.erl +++ b/erts/preloaded/src/erlang.erl @@ -1895,11 +1895,10 @@ spawn_opt(_Tuple) -> (runtime) -> {Total_Run_Time, Time_Since_Last_Call} when Total_Run_Time :: non_neg_integer(), Time_Since_Last_Call :: non_neg_integer(); - (scheduler_wall_time) -> [{Scheduler_Id, Scheduler_Worked_Time, Scheduler_Total_Time}] | - undefined when - Scheduler_Id :: pos_integer(), - Scheduler_Worked_Time :: non_neg_integer(), - Scheduler_Total_Time :: non_neg_integer(); + (scheduler_wall_time) -> [{SchedulerId, ActiveTime, TotalTime}] | undefined when + SchedulerId :: pos_integer(), + ActiveTime :: non_neg_integer(), + TotalTime :: non_neg_integer(); (wall_clock) -> {Total_Wallclock_Time, Wallclock_Time_Since_Last_Call} when Total_Wallclock_Time :: non_neg_integer(), -- cgit v1.2.3