From 9e2a3c9f5666676038b98092756e3560f285d4c5 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Wed, 13 May 2015 15:58:36 +0200 Subject: Doc fixes --- erts/doc/src/erlang.xml | 358 +++++++++++++++++++++++++----------------------- 1 file changed, 189 insertions(+), 169 deletions(-) (limited to 'erts/doc/src') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 6ca57566aa..3fea64cef5 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -539,55 +539,94 @@ Cancel a timer -

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:

+

+ Cancels a timer that has been created by either + erlang:start_timer(), + or erlang:send_after(). + TimerRef identifies the timer, and + was returned by the BIF that created the 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.

 +

+ Asynchronous request for cancellation. Async + defaults to false which will cause the + cancellation to be performed synchronously. When + Async is set to true, the cancel + operation will be performed asynchronously. That is, + erlang:cancel_timer() will send an asynchronous + 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.

 +

+ Request information about the Result + of the cancellation. Info defaults to true + which means that the Result will + be given. When Info is set to false, no + information about the result of the cancellation + will be given. When the operation is performed

+ + synchronously + +

+ If Info is true, the Result will + returned by erlang:cancel_timer(); otherwise, + ok will be returned. +

+ + asynchronously + +

+ If Info is true, a message on the form + {cancel_timer, TimerRef, + Result} will be sent to the + caller of erlang:cancel_timer() when the + cancellation operation has been performed; otherwise, + no message will be sent. +

+ + + -

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.

 +

+ More Options may be added in the future. +

+

+ When the Result equals false, a + timer corresponding to TimerRef could not + be found. This can be either because the timer had expired, + already had been canceled, or because TimerRef + never has corresponded to a timer. If the timer has expired, + the timeout message has been sent, but it does not tell you + whether or not it has arrived at its destination yet. When the + Result is an integer, it represents the + time in milli-seconds left until 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. If this is the case, communication + with the timer service will take much longer time than if it + is located locally. If the calling process is in critical + path, and can do other things while waiting for the result + of this operation, or is not interested in the result of + the operation, you want to use the {async, true} + option. If using the {async, false} option, the calling + process will be blocked until the operation has been + performed. +

+

See also erlang:send_after/4, erlang:start_timer/4, and erlang:read_timer/2.

-

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

 @@ -596,7 +635,7 @@

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

+ []).

 @@ -4548,37 +4587,60 @@ os_prompt% 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().

+

+ Read the state of a timer that has been created by either + erlang:start_timer(), + or erlang:send_after(). + TimerRef identifies the timer, and + was returned by the BIF that created the 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.

 +

+ Asynchronous request for state information. Async + defaults to false which will cause the operation + to be performed synchronously. In this case, the Result + will be returned by erlang:read_timer(). When + Async is set to true, erlang:read_timer() + will send an asynchronous request for the state information + to the 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 erlang: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.

 +

+ More Options may be added in the future. +

+

+ When the Result equals false, a + timer corresponding to TimerRef could not + be found. This can be either because the timer had expired, + had been canceled, or because TimerRef + never has corresponded to a timer. If the timer has expired, + the timeout message has been sent, but it does not tell you + whether or not it has arrived at its destination yet. When the + Result is an integer, it represents the + time in milli-seconds left until 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. If this is the case, communication + with the timer service will take much longer time than if it + is located locally. 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. If using the {async, false} option, the calling + process will be blocked until the operation has been + performed. +

+

See also erlang:send_after/4, erlang:start_timer/4, @@ -4592,7 +4654,7 @@ os_prompt%

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

+ []).

 @@ -4744,48 +4806,14 @@ 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.

+

+ Starts a timer. When the timer expires, the message + Msg will be sent to the process + identified by Dest. Appart from + the format of the message sent to + Dest when the timer expires + erlang:send_after/4 works exactly as + erlang:start_timer/4.

 @@ -4793,36 +4821,8 @@ true Start a timer

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

- - - - - 0 <= Time <= 4294967295 - Start a timer - -

Starts a timer which will send the message 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.

-

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:start_timer/3, - erlang:cancel_timer/2, - and - erlang:read_timer/2.

-

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

+ erlang:send_after(Time, + Dest, Msg, []).

 @@ -5231,41 +5231,59 @@ true Start a timer -

Starts a timer. When the timer expires, the message +

+ 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:

+ will be sent to the process identified by + Dest. +

+

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.

+

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

-

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().

+

+ More Options may be added in the future. +

+

+ The absolute point in time that the timer is set to expire on + has to be in the interval + [erlang:system_info(start_time), + erlang:system_info(end_time)]. + Further, if a relative time is specified, the Time value + is not allowed to be negative. +

+

+ If Dest is a pid(), it has to + be a pid() of a process created on the current + runtime system instance. This process may or may not + have terminated. If Dest is an + atom(), it will be interpreted as the name of a + locally registered process. The process referred to by the + name is looked up at the time of timer expiration. 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_after/4, erlang:cancel_timer/2, @@ -5281,7 +5299,7 @@ true

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

+ Dest, Msg, []).

 @@ -6845,7 +6863,9 @@ ok

The Erlang monotonic time in native time unit at the - time when current Erlang runtime system instance started.

 + time when current Erlang runtime system instance started. See also + erlang:system_info(end_time). +

system_version

Returns a string containing version number and -- cgit v1.2.3