diff options
Diffstat (limited to 'erts/doc/src/erlang.xml')
| -rw-r--r-- | erts/doc/src/erlang.xml | 249 |
1 files changed, 207 insertions, 42 deletions
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 @@ </desc> </func> <func> - <name name="cancel_timer" arity="1"/> + <name name="cancel_timer" arity="2"/> <fsummary>Cancel a timer</fsummary> <desc> - <p>Cancels a timer, where <c><anno>TimerRef</anno></c> was returned by - either - <seealso marker="#send_after/3">erlang:send_after/3</seealso> - or - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>. - If the timer is there to be removed, the function returns - the time in milliseconds left until the timer would have expired, - otherwise <c>false</c> (which means that <c><anno>TimerRef</anno></c> was - never a timer, that it has already been cancelled, or that it - has already delivered its message).</p> + <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> + <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> + <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> + </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>See also - <seealso marker="#send_after/3">erlang:send_after/3</seealso>, - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>, + <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/1">erlang:read_timer/1</seealso>.</p> + <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> + <name name="cancel_timer" arity="1"/> + <fsummary>Cancel a timer</fsummary> + <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> + </desc> + </func> <func> <name name="check_old_code" arity="1"/> <fsummary>Check if a module has old code</fsummary> @@ -4505,23 +4545,54 @@ os_prompt% </pre> </desc> </func> <func> - <name name="read_timer" arity="1"/> - <fsummary>Number of milliseconds remaining for a timer</fsummary> - <desc> - <p><c><anno>TimerRef</anno></c> is a timer reference returned by - <seealso marker="#send_after/3">erlang:send_after/3</seealso> - or - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>. - If the timer is active, the function returns the time in - milliseconds left until the timer will expire, otherwise - <c>false</c> (which means that <c><anno>TimerRef</anno></c> was never a - timer, that it has been cancelled, or that it has already - delivered its message).</p> + <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>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> + </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>See also - <seealso marker="#send_after/3">erlang:send_after/3</seealso>, - <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>, + <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="#cancel_timer/1">erlang:cancel_timer/1</seealso>.</p> + <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>.</p> + </desc> + </func> + <func> + <name name="read_timer" arity="1"/> + <fsummary>Read the state of a timer</fsummary> + <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> </desc> </func> <func> @@ -4670,6 +4741,63 @@ true</pre> </desc> </func> <func> + <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> + </desc> + </func> + <func> + <name name="send_after" arity="3"/> + <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> @@ -4690,9 +4818,9 @@ true</pre> 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/1">erlang:cancel_timer/1</seealso>, + <seealso marker="#cancel_timer/2">erlang:cancel_timer/2</seealso>, and - <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p> + <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> </desc> @@ -5100,15 +5228,35 @@ true</pre> </desc> </func> <func> - <name name="start_timer" arity="3"/> - <type_desc variable="Time">0 <= Time <= 4294967295</type_desc> + <name name="start_timer" arity="4"/> <fsummary>Start a timer</fsummary> <desc> - <p>Starts a timer which will send the message - <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</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>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> + <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 @@ -5119,15 +5267,24 @@ true</pre> 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/3">erlang:send_after/3</seealso>, - <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>, + <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>, + <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>, and - <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p> + <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> </desc> </func> <func> + <name name="start_timer" arity="3"/> + <fsummary>Start a timer</fsummary> + <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> + </desc> + </func> + <func> <name name="statistics" arity="1" clause_i="1"/> <fsummary>Information about context switches</fsummary> <desc> @@ -6236,6 +6393,14 @@ ok (i.e. <c>system_info(dynamic_trace)</c> returns <c>dtrace</c> or <c>systemtap</c>).</p> </item> + <tag><marker id="system_info_end_time"/><c>end_time</c></tag> + <item><p>The last <seealso marker="#monotonic_time/0">Erlang monotonic + time</seealso> in <c>native</c> + <seealso marker="#type_time_unit">time unit</seealso> that + can be represented internally in the current Erlang runtime system + instance. The time between the + <seealso marker="#system_info_start_time">start time</seealso> and + the end time is at least a quarter of a millennium.</p></item> <tag><c>elib_malloc</c></tag> <item> <p>This option will be removed in a future release. |