From 849a2ed2db2bd54422ec9284468f80cc86978974 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Mon, 11 May 2015 17:56:03 +0200 Subject: Timer fixes, documentation, and test cases --- erts/doc/src/erlang.xml | 249 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 207 insertions(+), 42 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index ba5f80a9c1..6ca57566aa 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -536,29 +536,69 @@ - + Cancel a timer -

Cancels a timer, where TimerRef was returned by - either - erlang:send_after/3 - or - erlang:start_timer/3. - If the timer is there to be removed, the function returns - the time in milliseconds left until the timer would have expired, - otherwise false (which means that TimerRef was - never a timer, that it has already been cancelled, or that it - has already delivered its message).

+

Cancels a timer. TimerRef needs to refer to + a timer that was created by either + erlang:send_after(), + or erlang:start_timer().

+

Currently available Options:

+ + {async, Async} + +

Asynchronous request for cancellation. Async + defaults to false. That is the operation will be + performed synchronously. When Async is set to + true the cancel operation will be performed + asynchronously. That is, cancel_timer() will send + a request for cancellation to the timer service that + manages the timer, and then return ok.

 + {info, Info} + +

Request information about the Result of the + cancellation. Info defaults to true. That + is information will be given. When Info is set to + false no information about the result of the cancel + operation will be given. When the operation is performed + synchronously the Result will returned from + cancel_timer(). When the operation is performed + asynchronously, a message on the form + {cancel_timer, TimerRef, Result} + will be sent to the caller of cancel_timer() when + the operation has been performed.

 + +

When the Result equals false a timer + corresponding to TimerRef could not be found. This + can be either because the timer had expired, been canceled, or because + TimerRef do not correspond to a timer. When the + Result is an integer, it represents + the time in milli seconds left before the timer will expire.

+

The timer service that manages the timer may be co-located + with another scheduler than the scheduler that the calling process + is executing on. In this case communication with the timer + service will be performed using asynchronous signals. If the calling + process is in critical path and can do other things while waiting + for the result of this operation, you want to use the {async, true} + option.

See also - erlang:send_after/3, - erlang:start_timer/3, + erlang:send_after/4, + erlang:start_timer/4, and - erlang:read_timer/1.

+ erlang:read_timer/2.

Note: Cancelling a timer does not guarantee that the message has not already been delivered to the message queue.

 - + + + Cancel a timer + +

Cancels a timer. The same as calling + erlang:cancel_timer(TimerRef, + [{async, false}, {info, true}]).

+ + Check if a module has old code @@ -4505,23 +4545,54 @@ os_prompt% - - Number of milliseconds remaining for a timer - -

TimerRef is a timer reference returned by - erlang:send_after/3 - or - erlang:start_timer/3. - If the timer is active, the function returns the time in - milliseconds left until the timer will expire, otherwise - false (which means that TimerRef was never a - timer, that it has been cancelled, or that it has already - delivered its message).

+ + Read the state of a timer + +

Read the state of a timer. TimerRef + needs to refer to a timer that was created by either + erlang:send_after(), + or erlang:start_timer().

+

Currently available Options:

+ + {async, Async} + +

Asynchronous request. Async defaults to false. That + is the operation will be performed synchronously, and the Result + will returned from read_timer(). When Async is set to + true, read_timer() will send a request for the + Result to a timer service that manages the timer and then + return ok. A message on the format + {read_timer, TimerRef, Result} + will be sent to the caller of read_timer() when + the operation has been processed.

 + +

When the Result equals false a timer + corresponding to TimerRef could not be found. This + can be either because the timer had expired, been canceled, or because + TimerRef do not correspond to a timer. When the + Result is an integer, it represents + the time in milli seconds left before the timer will expire.

+

The timer service that manages the timer may be co-located + with another scheduler than the scheduler that the calling process + is executing on. In this case communication with the timer + service will be performed using asynchronous signals. If the calling + process is in critical path and can do other things while waiting + for the result of this operation, you want to use the {async, true} + option.

See also - erlang:send_after/3, - erlang:start_timer/3, + erlang:send_after/4, + erlang:start_timer/4, and - erlang:cancel_timer/1.

+ erlang:cancel_timer/2.

+ + + + + Read the state of a timer + +

Read the state of a timer. The same as calling + erlang:read_timer(TimerRef, + [{async, false}]).

 @@ -4669,6 +4740,63 @@ true + + + Start a timer + +

Starts a timer. When the timer expires, the message + Msg will be sent to + Dest.

+

If Dest is a pid() it has to + be a pid() of a local process, dead or alive.

+

Currently available Options:

+ + {abs, Abs} + +

Absolute timeout. When Abs is false + the Time value will be interpreted + as a time in milli-seconds relative current + Erlang + monotonic time. When Abs is true the + Time value will be interpreted as an absolute + Erlang monotonic time of milli second time unit. Abs + defaults to false.

+ + +

The absolute time when the timer is set to expire needs + to be in the range between + erlang:system_info(start_time) + and + erlang:system_info(end_time). + If a negative relative time is specified the time is not + allowed to be negative.

+

If Dest is an atom(), it is supposed to be the name of + a registered process. The process referred to by the name is + looked up at the time of delivery. No error is given if + the name does not refer to a process.

+

If Dest is a pid(), the timer will be automatically + canceled if the process referred to by the pid() is not alive, + or when the process exits. This feature was introduced in + erts version 5.4.11. Note that timers will not be + automatically canceled when Dest is an atom().

+

See also + erlang:send_timer/4, + erlang:cancel_timer/2, + and + erlang:read_timer/2.

+

Failure: badarg if the arguments does not satisfy + the requirements specified above.

+ + + + + Start a timer + +

Starts a timer. The same as calling + erlang:send_after(Time, + Dest, Msg, [{abs, false}]).

+ + 0 <= Time <= 4294967295 @@ -4690,9 +4818,9 @@ true automatically canceled when Dest is an atom.

See also erlang:start_timer/3, - erlang:cancel_timer/1, + erlang:cancel_timer/2, and - erlang:read_timer/1.

+ erlang:read_timer/2.

Failure: badarg if the arguments does not satisfy the requirements specified above.

@@ -5100,15 +5228,35 @@ true - - 0 <= Time <= 4294967295 + Start a timer -

Starts a timer which will send the message - {timeout, TimerRef, Msg} to Dest - after Time milliseconds.

-

If Dest is a pid() it has to be a pid() of a local process, dead or alive.

-

The Time value can, in the current implementation, not be greater than 4294967295.

+

Starts a timer. When the timer expires, the message + {timeout, TimerRef, Msg} + will be sent to Dest.

+

If Dest is a pid() it has to + be a pid() of a local process, dead or alive.

+

Currently available Options:

+ + {abs, Abs} + +

Absolute timeout. When Abs is false + the Time value will be interpreted + as a time in milli-seconds relative current + Erlang + monotonic time. When Abs is true the + Time value will be interpreted as an absolute + Erlang monotonic time of milli second time unit. Abs + defaults to false.

+ + +

The absolute time when the timer is set to expire needs + to be in the range between + erlang:system_info(start_time) + and + erlang:system_info(end_time). + If a negative relative time is specified the time is not + allowed to be negative.

If Dest is an atom(), it is supposed to be the name of a registered process. The process referred to by the name is looked up at the time of delivery. No error is given if @@ -5119,14 +5267,23 @@ true erts version 5.4.11. Note that timers will not be automatically canceled when Dest is an atom().

See also - erlang:send_after/3, - erlang:cancel_timer/1, + erlang:send_after/4, + erlang:cancel_timer/2, and - erlang:read_timer/1.

+ erlang:read_timer/2.

Failure: badarg if the arguments does not satisfy the requirements specified above.

 + + + Start a timer + +

Starts a timer. The same as calling + erlang:start_timer(Time, + Dest, Msg, [{abs, false}]).

+ + Information about context switches @@ -6236,6 +6393,14 @@ ok (i.e. system_info(dynamic_trace) returns dtrace or systemtap).

+ end_time +

The last Erlang monotonic + time in native + time unit that + can be represented internally in the current Erlang runtime system + instance. The time between the + start time and + the end time is at least a quarter of a millennium.

 elib_malloc

This option will be removed in a future release. -- cgit v1.2.3