From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/timer.xml | 380 ++++++++++++++++++++++++------------------- 1 file changed, 217 insertions(+), 163 deletions(-) (limited to 'lib/stdlib/doc/src/timer.xml') diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index 4f259d57a8..8f2ce36b06 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -30,26 +30,25 @@ 1998-09-09 D - timer.sgml + timer.xml timer - Timer Functions + Timer functions.

This module provides useful functions related to time. Unless otherwise - stated, time is always measured in milliseconds. All - timer functions return immediately, regardless of work carried - out by another process. -

-

Successful evaluations of the timer functions yield return values - containing a timer reference, denoted TRef below. By using - cancel/1, the returned reference can be used to cancel any - requested action. A TRef is an Erlang term, the contents - of which must not be altered. -

-

The timeouts are not exact, but should be at least as long - as requested. -

+ stated, time is always measured in milliseconds. All + timer functions return immediately, regardless of work done by another + process.

+

Successful evaluations of the timer functions give return values + containing a timer reference, denoted TRef. By using + cancel/1, + the returned reference can be used to cancel any + requested action. A TRef is an Erlang term, which contents + must not be changed.

+

The time-outs are not exact, but are at least as long + as requested.

 + @@ -60,231 +59,286 @@

A timer reference.

 + - - Start a global timer server (named timer_server). + + Apply Module:Function(Arguments) after a specified + Time. -

Starts the timer server. Normally, the server does not need - to be started explicitly. It is started dynamically if it - is needed. This is useful during development, but in a - target system the server should be started explicitly. Use - configuration parameters for kernel for this.

+

Evaluates apply(Module, Function, + Arguments) after Time + milliseconds.

+

Returns {ok, TRef} or + {error, Reason}.

 + - - Apply Module:Function(Arguments)after a specified Time. + + Evaluate Module:Function(Arguments) repeatedly at + intervals of Time. -

Evaluates apply(Module, Function, Arguments) after Time amount of time - has elapsed. Returns {ok, TRef}, or {error, Reason}.

+

Evaluates apply(Module, Function, + Arguments) repeatedly at intervals of + Time.

+

Returns {ok, TRef} or + {error, Reason}.

 + - - - Send Messageto Pidafter a specified Time. + + Cancel a previously requested time-out identified by + TRef. - - send_after/3 - -

Evaluates Pid ! Message after Time amount - of time has elapsed. (Pid can also be an atom of a - registered name.) Returns {ok, TRef}, or - {error, Reason}.

- - send_after/2 - -

Same as send_after(Time, self(), Message).

- - +

Cancels a previously requested time-out. TRef is + a unique + timer reference returned by the related timer function.

+

Returns {ok, cancel}, or {error, Reason} + when TRef is not a timer reference.

 + - - - Send an exit signal with Reasonafter a specified Time. + Send an exit signal with Reason after a specified + Time. + +

exit_after/2 is the same as + exit_after(Time, self(), + Reason1).

+

exit_after/3 sends an exit signal with reason + Reason1 to + pid Pid. Returns {ok, TRef} + or {error, Reason2}.

+ + + + + + Convert Hours+Minutes+Seconds to + Milliseconds. + +

Returns the number of milliseconds in Hours + + Minutes + Seconds.

+ + + + + + Convert Hours to Milliseconds. + +

Returns the number of milliseconds in Hours.

+ + + + + + + Send an exit signal with Reason after a specified + Time. + +

kill_after/1 is the same as + exit_after(Time, self(), kill).

+

kill_after/2 is the same as + exit_after(Time, Pid, kill).

+ + + + + + Converts Minutes to Milliseconds. + +

Returns the number of milliseconds in + Minutes.

+ + + + + + Calculate time difference between time stamps. + In microseconds + +

Calculates the time difference Tdiff = + T2 - T1 in microseconds, + where T1 and T2 + are time-stamp tuples on the same format as returned from + + erlang:timestamp/0 or + + os:timestamp/0.

+ + + + + + Convert Seconds to Milliseconds. + +

Returns the number of milliseconds in + Seconds.

+ + + + + + + Send Message to Pid after a specified + Time. - exit_after/3 - -

Send an exit signal with reason Reason1 to Pid - Pid. Returns {ok, TRef}, or - {error, Reason2}.

- - exit_after/2 - -

Same as exit_after(Time, self(), Reason1).

- - kill_after/2 + send_after/3 -

Same as exit_after(Time, Pid, kill).

+

Evaluates Pid ! Message after + Time milliseconds. (Pid + can also be an atom of a registered name.)

+

Returns {ok, TRef} or + {error, Reason}.

 - kill_after/1 + send_after/2 -

Same as exit_after(Time, self(), kill).

+

Same as send_after(Time, self(), + Message).

 - - - Evaluate Module:Function(Arguments)repeatedly at intervals of Time. - -

Evaluates apply(Module, Function, Arguments) repeatedly at - intervals of Time. Returns {ok, TRef}, or - {error, Reason}.

- - + - Send Messagerepeatedly at intervals of Time. + Send Message repeatedly at intervals of Time. + send_interval/3 -

Evaluates Pid ! Message repeatedly after Time - amount of time has elapsed. (Pid can also be an atom of - a registered name.) Returns {ok, TRef} or +

Evaluates Pid ! Message + repeatedly after Time milliseconds. + (Pid can also be + an atom of a registered name.)

+

Returns {ok, TRef} or {error, Reason}.

 send_interval/2 -

Same as send_interval(Time, self(), Message).

+

Same as send_interval(Time, self(), + Message).

 + - - Cancel a previously requested timeout identified by TRef. + + Suspend the calling process for Time milliseconds. + -

Cancels a previously requested timeout. TRef is a unique - timer reference returned by the timer function in question. Returns - {ok, cancel}, or {error, Reason} when TRef - is not a timer reference.

+

Suspends the process calling this function for + Time milliseconds and then returns ok, + or suspends the process forever if Time is the + atom infinity. Naturally, this + function does not return immediately.

 + - - Suspend the calling process for Timeamount of milliseconds. + + Start a global timer server (named timer_server). + -

Suspends the process calling this function for Time amount - of milliseconds and then returns ok, or suspend the process - forever if Time is the atom infinity. Naturally, this - function does not return immediately.

+

Starts the timer server. Normally, the server does not need + to be started explicitly. It is started dynamically if it + is needed. This is useful during development, but in a + target system the server is to be started explicitly. Use + configuration parameters for + Kernel for this.

 + Measure the real time it takes to evaluate apply(Module, - Function, Arguments) or apply(Fun, Arguments) + Function, Arguments) or apply(Fun, Arguments). In microseconds tc/3 -

Evaluates apply(Module, Function, Arguments) and measures - the elapsed real time as reported by os:timestamp/0. - Returns {Time, Value}, where - Time is the elapsed real time in microseconds, - and Value is what is returned from the apply.

+

Evaluates apply(Module, Function, + Arguments) and measures the elapsed real time as + reported by + os:timestamp/0.

+

Returns {Time, Value}, where + Time is the elapsed real time in + microseconds, and Value is what is + returned from the apply.

 tc/2 -

Evaluates apply(Fun, Arguments). Otherwise works - like tc/3.

+

Evaluates apply(Fun, Arguments). + Otherwise the same as tc/3.

 tc/1 -

Evaluates Fun(). Otherwise works like tc/2.

+

Evaluates Fun(). Otherwise the same as + tc/2.

 - - - - Calculate time difference between timestamps - In microseconds - -

Calculates the time difference Tdiff = T2 - T1 in - microseconds, where T1 and T2 - are timestamp tuples on the same format as returned from - erlang:timestamp/0, - or os:timestamp/0.

- - - - - Convert Secondsto Milliseconds. - -

Returns the number of milliseconds in Seconds.

- - - - - Converts Minutes to Milliseconds. - -

Return the number of milliseconds in Minutes.

- - - - - Convert Hoursto Milliseconds. - -

Returns the number of milliseconds in Hours.

- - - - - Convert Hours+Minutes+Secondsto Milliseconds. - -

Returns the number of milliseconds in Hours + Minutes + Seconds.

- -
Examples -

This example illustrates how to print out "Hello World!" in 5 seconds:

+

Example 1

+

The following example shows how to print "Hello World!" in 5 seconds:

-      1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]).
-      {ok,TRef}
-      Hello World!
-

The following coding example illustrates a process which performs a - certain action and if this action is not completed within a certain - limit, then the process is killed.

+1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]). +{ok,TRef} +Hello World! + +

Example 2

+

The following example shows a process performing a + certain action, and if this action is not completed within a certain + limit, the process is killed:

- Pid = spawn(mod, fun, [foo, bar]), - %% If pid is not finished in 10 seconds, kill him - {ok, R} = timer:kill_after(timer:seconds(10), Pid), - ... - %% We change our mind... - timer:cancel(R), - ... +Pid = spawn(mod, fun, [foo, bar]), +%% If pid is not finished in 10 seconds, kill him +{ok, R} = timer:kill_after(timer:seconds(10), Pid), +... +%% We change our mind... +timer:cancel(R), +...
- WARNING -

A timer can always be removed by calling cancel/1. -

-

An interval timer, i.e. a timer created by evaluating any of the - functions apply_interval/4, send_interval/3, and - send_interval/2, is linked to the process towards which - the timer performs its task. -

-

A one-shot timer, i.e. a timer created by evaluating any of the - functions apply_after/4, send_after/3, - send_after/2, exit_after/3, exit_after/2, - kill_after/2, and kill_after/1 is not linked to any - process. Hence, such a timer is removed only when it reaches its - timeout, or if it is explicitly removed by a call to cancel/1.

+ Notes +

A timer can always be removed by calling + cancel/1.

+ +

An interval timer, that is, a timer created by evaluating any of the + functions + apply_interval/4, + send_interval/3, and + send_interval/2 + is linked to the process to which the timer performs its task.

+ +

A one-shot timer, that is, a timer created by evaluating any of the + functions + apply_after/4, + send_after/3, + send_after/2, + exit_after/3, + exit_after/2, + kill_after/2, and + kill_after/1 + is not linked to any process. Hence, such a timer is removed only + when it reaches its time-out, or if it is explicitly removed by a call to + cancel/1.

-- cgit v1.2.3