diff options
| -rw-r--r-- | erts/doc/src/erlang.xml | 358 |
1 files changed, 189 insertions, 169 deletions
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 @@ <name name="cancel_timer" arity="2"/> <fsummary>Cancel a timer</fsummary> <desc> - <p>Cancels a timer. <c><anno>TimerRef</anno></c> needs to refer to - a timer that was created by either - <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>, - or <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>.</p> - <p>Currently available <c><anno>Option</anno>s</c>:</p> + <p> + Cancels a timer that has been created by either + <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>, + or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>. + <c><anno>TimerRef</anno></c> identifies the timer, and + was returned by the BIF that created the timer. + </p> + <p>Currently available <c><anno>Option</anno></c>s:</p> <taglist> <tag><c>{async, Async}</c></tag> <item> - <p>Asynchronous request for cancellation. <c>Async</c> - defaults to <c>false</c>. That is the operation will be - performed synchronously. When <c>Async</c> is set to - <c>true</c> the cancel operation will be performed - asynchronously. That is, <c>cancel_timer()</c> will send - a request for cancellation to the timer service that - manages the timer, and then return <c>ok</c>.</p></item> + <p> + Asynchronous request for cancellation. <c>Async</c> + defaults to <c>false</c> which will cause the + cancellation to be performed synchronously. When + <c>Async</c> is set to <c>true</c>, the cancel + operation will be performed asynchronously. That is, + <c>erlang:cancel_timer()</c> will send an asynchronous + request for cancellation to the timer service that + manages the timer, and then return <c>ok</c>. + </p> + </item> <tag><c>{info, Info}</c></tag> <item> - <p>Request information about the <c>Result</c> of the - cancellation. <c>Info</c> defaults to <c>true</c>. That - is information will be given. When <c>Info</c> is set to - <c>false</c> no information about the result of the cancel - operation will be given. When the operation is performed - synchronously the <c>Result</c> will returned from - <c>cancel_timer()</c>. When the operation is performed - asynchronously, a message on the form - <c>{cancel_timer, <anno>TimerRef</anno>, <anno>Result</anno>}</c> - will be sent to the caller of <c>cancel_timer()</c> when - the operation has been performed.</p></item> + <p> + Request information about the <c><anno>Result</anno></c> + of the cancellation. <c>Info</c> defaults to <c>true</c> + which means that the <c><anno>Result</anno></c> will + be given. When <c>Info</c> is set to <c>false</c>, no + information about the result of the cancellation + will be given. When the operation is performed</p> + <taglist> + <tag>synchronously</tag> + <item> + <p> + If <c>Info</c> is <c>true</c>, the <c>Result</c> will + returned by <c>erlang:cancel_timer()</c>; otherwise, + <c>ok</c> will be returned. + </p> + </item> + <tag>asynchronously</tag> + <item> + <p> + If <c>Info</c> is <c>true</c>, a message on the form + <c>{cancel_timer, <anno>TimerRef</anno>, + <anno>Result</anno>}</c> will be sent to the + caller of <c>erlang:cancel_timer()</c> when the + cancellation operation has been performed; otherwise, + no message will be sent. + </p> + </item> + </taglist> + </item> </taglist> - <p>When the <c><anno>Result</anno></c> equals <c>false</c> a timer - corresponding to <c><anno>TimerRef</anno></c> could not be found. This - can be either because the timer had expired, been canceled, or because - <c><anno>TimerRef</anno></c> do not correspond to a timer. When the - <c><anno>Result</anno></c> is an integer, it represents - the time in milli seconds left before the timer will expire.</p> - <note><p>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 <c>{async, true}</c> - option.</p></note> + <p> + More <c><anno>Option</anno></c>s may be added in the future. + </p> + <p> + When the <c><anno>Result</anno></c> equals <c>false</c>, a + timer corresponding to <c><anno>TimerRef</anno></c> could not + be found. This can be either because the timer had expired, + already had been canceled, or because <c><anno>TimerRef</anno></c> + 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 + <c><anno>Result</anno></c> is an integer, it represents the + time in milli-seconds left until the timer will expire. + </p> + <note> + <p> + 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 <c>{async, true}</c> + option. If using the <c>{async, false}</c> option, the calling + process will be blocked until the operation has been + performed. + </p> + </note> <p>See also <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>, and <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p> - <p>Note: Cancelling a timer does not guarantee that the message - has not already been delivered to the message queue.</p> </desc> </func> <func> @@ -596,7 +635,7 @@ <desc> <p>Cancels a timer. The same as calling <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer(TimerRef, - [{async, false}, {info, true}])</c></seealso>.</p> + [])</c></seealso>.</p> </desc> </func> <func> @@ -4548,37 +4587,60 @@ os_prompt% </pre> <name name="read_timer" arity="2"/> <fsummary>Read the state of a timer</fsummary> <desc> - <p>Read the state of a timer. <c><anno>TimerRef</anno></c> - needs to refer to a timer that was created by either - <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>, - or <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>.</p> + <p> + Read the state of a timer that has been created by either + <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>, + or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>. + <c><anno>TimerRef</anno></c> identifies the timer, and + was returned by the BIF that created the timer. + </p> <p>Currently available <c><anno>Option</anno>s</c>:</p> <taglist> <tag><c>{async, Async}</c></tag> <item> - <p>Asynchronous request. <c>Async</c> defaults to <c>false</c>. That - is the operation will be performed synchronously, and the <c>Result</c> - will returned from <c>read_timer()</c>. When <c>Async</c> is set to - <c>true</c>, <c>read_timer()</c> will send a request for the - <c>Result</c> to a timer service that manages the timer and then - return <c>ok</c>. A message on the format - <c>{read_timer, <anno>TimerRef</anno>, <anno>Result</anno>}</c> - will be sent to the caller of <c>read_timer()</c> when - the operation has been processed.</p></item> + <p> + Asynchronous request for state information. <c>Async</c> + defaults to <c>false</c> which will cause the operation + to be performed synchronously. In this case, the <c>Result</c> + will be returned by <c>erlang:read_timer()</c>. When + <c>Async</c> is set to <c>true</c>, <c>erlang:read_timer()</c> + will send an asynchronous request for the state information + to the timer service that manages the timer, and then return + <c>ok</c>. A message on the format <c>{read_timer, + <anno>TimerRef</anno>, <anno>Result</anno>}</c> will be + sent to the caller of <c>erlang:read_timer()</c> when the + operation has been processed. + </p> + </item> </taglist> - <p>When the <c><anno>Result</anno></c> equals <c>false</c> a timer - corresponding to <c><anno>TimerRef</anno></c> could not be found. This - can be either because the timer had expired, been canceled, or because - <c><anno>TimerRef</anno></c> do not correspond to a timer. When the - <c><anno>Result</anno></c> is an integer, it represents - the time in milli seconds left before the timer will expire.</p> - <note><p>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 <c>{async, true}</c> - option.</p></note> + <p> + More <c><anno>Option</anno></c>s may be added in the future. + </p> + <p> + When the <c><anno>Result</anno></c> equals <c>false</c>, a + timer corresponding to <c><anno>TimerRef</anno></c> could not + be found. This can be either because the timer had expired, + had been canceled, or because <c><anno>TimerRef</anno></c> + 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 + <c><anno>Result</anno></c> is an integer, it represents the + time in milli-seconds left until the timer will expire. + </p> + <note> + <p> + 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 <c>{async, true}</c> + option. If using the <c>{async, false}</c> option, the calling + process will be blocked until the operation has been + performed. + </p> + </note> <p>See also <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>, @@ -4592,7 +4654,7 @@ os_prompt% </pre> <desc> <p>Read the state of a timer. The same as calling <seealso marker="#read_timer/2"><c>erlang:read_timer(TimerRef, - [{async, false}])</c></seealso>.</p> + [])</c></seealso>.</p> </desc> </func> <func> @@ -4744,48 +4806,14 @@ true</pre> <name name="send_after" arity="4"/> <fsummary>Start a timer</fsummary> <desc> - <p>Starts a timer. When the timer expires, the message - <c><anno>Msg</anno></c> will be sent to - <c><anno>Dest</anno></c>.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to - be a <c>pid()</c> of a local process, dead or alive.</p> - <p>Currently available <c><anno>Option</anno>s</c>:</p> - <taglist> - <tag><c>{abs, Abs}</c></tag> - <item> - <p>Absolute timeout. When <c>Abs</c> is <c>false</c> - the <c><anno>Time</anno></c> value will be interpreted - as a time in milli-seconds relative current - <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang - monotonic time</seealso>. When <c>Abs</c> is <c>true</c> the - <c><anno>Time</anno></c> value will be interpreted as an absolute - Erlang monotonic time of milli second time unit. <c>Abs</c> - defaults to <c>false</c>.</p> - </item> - </taglist> - <p>The absolute time when the timer is set to expire needs - to be in the range between - <seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso> - and - <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>. - If a negative relative time is specified the time is not - allowed to be negative.</p> - <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, 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.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically - canceled if the process referred to by the <c>pid()</c> 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 <c><anno>Dest</anno></c> is an <c>atom()</c>.</p> - <p>See also - <seealso marker="#start_timer/4"><c>erlang:send_timer/4</c></seealso>, - <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>, - and - <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p> - <p>Failure: <c>badarg</c> if the arguments does not satisfy - the requirements specified above.</p> + <p> + Starts a timer. When the timer expires, the message + <c><anno>Msg</anno></c> will be sent to the process + identified by <c><anno>Dest</anno></c>. Appart from + the format of the message sent to + <c><anno>Dest</anno></c> when the timer expires + <c>erlang:send_after/4</c> works exactly as + <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>.</p> </desc> </func> <func> @@ -4793,36 +4821,8 @@ true</pre> <fsummary>Start a timer</fsummary> <desc> <p>Starts a timer. The same as calling - <seealso marker="#send_timer/4"><c>erlang:send_after(<anno>Time</anno>, - <anno>Dest</anno>, <anno>Msg</anno>, [{abs, false}])</c></seealso>.</p> - </desc> - </func> - <func> - <name name="send_after" arity="3"/> - <type_desc variable="Time">0 <= Time <= 4294967295</type_desc> - <fsummary>Start a timer</fsummary> - <desc> - <p>Starts a timer which will send the message <c>Msg</c> - to <c><anno>Dest</anno></c> after <c><anno>Time</anno></c> milliseconds.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to be a <c>pid()</c> of a local process, dead or alive.</p> - <p>The <c><anno>Time</anno></c> value can, in the current implementation, not be greater than 4294967295.</p> - <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, 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.</p> - - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically - canceled if the process referred to by the <c>pid()</c> 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 <c><anno>Dest</anno></c> is an <c>atom</c>.</p> - <p>See also - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>, - <seealso marker="#cancel_timer/2">erlang:cancel_timer/2</seealso>, - and - <seealso marker="#read_timer/2">erlang:read_timer/2</seealso>.</p> - <p>Failure: <c>badarg</c> if the arguments does not satisfy - the requirements specified above.</p> + <seealso marker="#send_after/4"><c>erlang:send_after(<anno>Time</anno>, + <anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p> </desc> </func> <func> @@ -5231,41 +5231,59 @@ true</pre> <name name="start_timer" arity="4"/> <fsummary>Start a timer</fsummary> <desc> - <p>Starts a timer. When the timer expires, the message + <p> + Starts a timer. When the timer expires, the message <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c> - will be sent to <c><anno>Dest</anno></c>.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to - be a <c>pid()</c> of a local process, dead or alive.</p> - <p>Currently available <c><anno>Option</anno>s</c>:</p> + will be sent to the process identified by + <c><anno>Dest</anno></c>. + </p> + <p>Currently available <c><anno>Option</anno></c>s:</p> <taglist> <tag><c>{abs, Abs}</c></tag> <item> - <p>Absolute timeout. When <c>Abs</c> is <c>false</c> - the <c><anno>Time</anno></c> value will be interpreted - as a time in milli-seconds relative current - <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang - monotonic time</seealso>. When <c>Abs</c> is <c>true</c> the - <c><anno>Time</anno></c> value will be interpreted as an absolute - Erlang monotonic time of milli second time unit. <c>Abs</c> - defaults to <c>false</c>.</p> + <p> + Absolute <c><anno>Time</anno></c> value. <c>Abs</c> + defaults to <c>false</c> which means that the + <c><anno>Time</anno></c> value will be interpreted + as a time in milli-seconds relative current + <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang + monotonic time</seealso>. When <c>Abs</c> is set to + <c>true</c>, the <c><anno>Time</anno></c> value will + be interpreted as an absolute Erlang monotonic time of + milli-seconds + <seealso marker="#type_time_unit">time unit</seealso>. + </p> </item> </taglist> - <p>The absolute time when the timer is set to expire needs - to be in the range between - <seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso> - and - <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>. - If a negative relative time is specified the time is not - allowed to be negative.</p> - <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, 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.</p> - <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically - canceled if the process referred to by the <c>pid()</c> 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 <c><anno>Dest</anno></c> is an <c>atom()</c>.</p> + <p> + More <c><anno>Option</anno></c>s may be added in the future. + </p> + <p> + The absolute point in time that the timer is set to expire on + has to be in the interval + <c>[</c><seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso><c>, + </c><seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso><c>]</c>. + Further, if a relative time is specified, the <c><anno>Time</anno></c> value + is not allowed to be negative. + </p> + <p> + If <c><anno>Dest</anno></c> is a <c>pid()</c>, it has to + be a <c>pid()</c> of a process created on the current + runtime system instance. This process may or may not + have terminated. If <c><anno>Dest</anno></c> is an + <c>atom()</c>, 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. + </p> + <p> + If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will + be automatically canceled if the process referred to by the + <c>pid()</c> 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 + <c><anno>Dest</anno></c> is an <c>atom()</c>. + </p> <p>See also <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>, @@ -5281,7 +5299,7 @@ true</pre> <desc> <p>Starts a timer. The same as calling <seealso marker="#start_timer/4"><c>erlang:start_timer(<anno>Time</anno>, - <anno>Dest</anno>, <anno>Msg</anno>, [{abs, false}])</c></seealso>.</p> + <anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p> </desc> </func> <func> @@ -6845,7 +6863,9 @@ ok <item><p>The <seealso marker="#monotonic_time/0">Erlang monotonic time</seealso> in <c>native</c> <seealso marker="#type_time_unit">time unit</seealso> at the - time when current Erlang runtime system instance started.</p></item> + time when current Erlang runtime system instance started. See also + <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>. + </p></item> <tag><c>system_version</c></tag> <item> <p>Returns a string containing version number and |