<?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. </legalnotice> <title>timer</title> <prepared>Sebastian Strollo</prepared> <responsible>Bjarne Däcker</responsible> <docno>1</docno> <approved>Bjarne Däcker</approved> <checked></checked> <date>1998-09-09</date> <rev>D</rev> <file>timer.sgml</file> </header> <module>timer</module> <modulesummary>Timer Functions</modulesummary> <description> <p>This module provides useful functions related to time. Unless otherwise stated, time is always measured in <c>milliseconds</c>. All timer functions return immediately, regardless of work carried out by another process. </p> <p>Successful evaluations of the timer functions yield return values containing a timer reference, denoted <c>TRef</c> below. By using <c>cancel/1</c>, the returned reference can be used to cancel any requested action. A <c>TRef</c> is an Erlang term, the contents of which must not be altered. </p> <p>The timeouts are not exact, but should be <c>at least</c> as long as requested. </p> </description> <datatypes> <datatype> <name name="time"/> <desc><p>Time in milliseconds.</p></desc> </datatype> <datatype> <name name="tref"/> <desc><p>A timer reference.</p></desc> </datatype> </datatypes> <funcs> <func> <name name="start" arity="0"/> <fsummary>Start a global timer server (named <c>timer_server</c>).</fsummary> <desc> <p>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 <c>kernel</c> for this.</p> </desc> </func> <func> <name name="apply_after" arity="4"/> <fsummary>Apply <c>Module:Function(Arguments)</c>after a specified <c>Time</c>.</fsummary> <desc> <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> after <c><anno>Time</anno></c> amount of time has elapsed. Returns <c>{ok, <anno>TRef</anno>}</c>, or <c>{error, <anno>Reason</anno>}</c>.</p> </desc> </func> <func> <name name="send_after" arity="2"/> <name name="send_after" arity="3"/> <fsummary>Send <c>Message</c>to <c>Pid</c>after a specified <c>Time</c>.</fsummary> <desc> <p> <taglist> <tag><c>send_after/3</c></tag> <item> <p>Evaluates <c><anno>Pid</anno> ! <anno>Message</anno></c> after <c><anno>Time</anno></c> amount of time has elapsed. (<c><anno>Pid</anno></c> can also be an atom of a registered name.) Returns <c>{ok, <anno>TRef</anno>}</c>, or <c>{error, <anno>Reason</anno>}</c>.</p> </item> <tag><c>send_after/2</c></tag> <item> <p>Same as <c>send_after(<anno>Time</anno>, self(), <anno>Message</anno>)</c>.</p> </item> </taglist> </p> </desc> </func> <func> <name name="kill_after" arity="1"/> <name name="kill_after" arity="2"/> <name name="exit_after" arity="2"/> <name name="exit_after" arity="3"/> <fsummary>Send an exit signal with <c>Reason</c>after a specified <c>Time</c>.</fsummary> <desc> <p> <taglist> <tag><c>exit_after/3</c></tag> <item> <p>Send an exit signal with reason <c><anno>Reason1</anno></c> to Pid <c><anno>Pid</anno></c>. Returns <c>{ok, <anno>TRef</anno>}</c>, or <c>{error, <anno>Reason2</anno>}</c>.</p> </item> <tag><c>exit_after/2</c></tag> <item> <p>Same as <c>exit_after(<anno>Time</anno>, self(), <anno>Reason1</anno>)</c>. </p> </item> <tag><c>kill_after/2</c></tag> <item> <p>Same as <c>exit_after(<anno>Time</anno>, <anno>Pid</anno>, kill)</c>. </p> </item> <tag><c>kill_after/1</c></tag> <item> <p>Same as <c>exit_after(<anno>Time</anno>, self(), kill)</c>. </p> </item> </taglist> </p> </desc> </func> <func> <name name="apply_interval" arity="4"/> <fsummary>Evaluate <c>Module:Function(Arguments)</c>repeatedly at intervals of <c>Time</c>.</fsummary> <desc> <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> repeatedly at intervals of <c><anno>Time</anno></c>. Returns <c>{ok, <anno>TRef</anno>}</c>, or <c>{error, <anno>Reason</anno>}</c>.</p> </desc> </func> <func> <name name="send_interval" arity="2"/> <name name="send_interval" arity="3"/> <fsummary>Send <c>Message</c>repeatedly at intervals of <c>Time</c>.</fsummary> <desc> <p> <taglist> <tag><c>send_interval/3</c></tag> <item> <p>Evaluates <c><anno>Pid</anno> ! <anno>Message</anno></c> repeatedly after <c><anno>Time</anno></c> amount of time has elapsed. (<c><anno>Pid</anno></c> can also be an atom of a registered name.) Returns <c>{ok, <anno>TRef</anno>}</c> or <c>{error, <anno>Reason</anno>}</c>.</p> </item> <tag><c>send_interval/2</c></tag> <item> <p>Same as <c>send_interval(<anno>Time</anno>, self(), <anno>Message</anno>)</c>.</p> </item> </taglist> </p> </desc> </func> <func> <name name="cancel" arity="1"/> <fsummary>Cancel a previously requested timeout identified by <c>TRef</c>.</fsummary> <desc> <p>Cancels a previously requested timeout. <c><anno>TRef</anno></c> is a unique timer reference returned by the timer function in question. Returns <c>{ok, cancel}</c>, or <c>{error, <anno>Reason</anno>}</c> when <c><anno>TRef</anno></c> is not a timer reference.</p> </desc> </func> <func> <name name="sleep" arity="1"/> <fsummary>Suspend the calling process for <c>Time</c>amount of milliseconds.</fsummary> <desc> <p>Suspends the process calling this function for <c><anno>Time</anno></c> amount of milliseconds and then returns <c>ok</c>, or suspend the process forever if <c><anno>Time</anno></c> is the atom <c>infinity</c>. Naturally, this function does <em>not</em> return immediately.</p> </desc> </func> <func> <name name="tc" arity="1"/> <name name="tc" arity="2"/> <name name="tc" arity="3"/> <fsummary>Measure the real time it takes to evaluate <c>apply(Module, Function, Arguments)</c> or <c>apply(Fun, Arguments)</c></fsummary> <type_desc variable="Time">In microseconds</type_desc> <desc> <p> <taglist> <tag><c>tc/3</c></tag> <item> <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> and measures the elapsed real time as reported by <c>os:timestamp/0</c>. Returns <c>{<anno>Time</anno>, <anno>Value</anno>}</c>, where <c><anno>Time</anno></c> is the elapsed real time in <em>microseconds</em>, and <c><anno>Value</anno></c> is what is returned from the apply.</p> </item> <tag><c>tc/2</c></tag> <item> <p>Evaluates <c>apply(<anno>Fun</anno>, <anno>Arguments</anno>)</c>. Otherwise works like <c>tc/3</c>.</p> </item> <tag><c>tc/1</c></tag> <item> <p>Evaluates <c><anno>Fun</anno>()</c>. Otherwise works like <c>tc/2</c>.</p> </item> </taglist> </p> </desc> </func> <func> <name name="now_diff" arity="2"/> <fsummary>Calculate time difference between <c>now/0</c>timestamps</fsummary> <type_desc variable="Tdiff">In microseconds</type_desc> <desc> <p>Calculates the time difference <c><anno>Tdiff</anno> = <anno>T2</anno> - <anno>T1</anno></c> in <em>microseconds</em>, where <c><anno>T1</anno></c> and <c><anno>T2</anno></c> probably are timestamp tuples returned from <c>erlang:now/0</c>.</p> </desc> </func> <func> <name name="seconds" arity="1"/> <fsummary>Convert <c>Seconds</c>to <c>Milliseconds</c>.</fsummary> <desc> <p>Returns the number of milliseconds in <c><anno>Seconds</anno></c>.</p> </desc> </func> <func> <name name="minutes" arity="1"/> <fsummary>Converts <c>Minutes</c>to <c>Milliseconds</c>.</fsummary> <desc> <p>Return the number of milliseconds in <c><anno>Minutes</anno></c>.</p> </desc> </func> <func> <name name="hours" arity="1"/> <fsummary>Convert <c>Hours</c>to <c>Milliseconds</c>.</fsummary> <desc> <p>Returns the number of milliseconds in <c><anno>Hours</anno></c>.</p> </desc> </func> <func> <name name="hms" arity="3"/> <fsummary>Convert <c>Hours</c>+<c>Minutes</c>+<c>Seconds</c>to <c>Milliseconds</c>.</fsummary> <desc> <p>Returns the number of milliseconds in <c><anno>Hours</anno> + <anno>Minutes</anno> + <anno>Seconds</anno></c>.</p> </desc> </func> </funcs> <section> <title>Examples</title> <p>This example illustrates how to print out "Hello World!" in 5 seconds:</p> <pre> 1> <input>timer:apply_after(5000, io, format, ["~nHello World!~n", []]).</input> {ok,TRef} Hello World!</pre> <p>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.</p> <code type="none"> 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), ...</code> </section> <section> <title>WARNING</title> <p>A timer can always be removed by calling <c>cancel/1</c>. </p> <p>An interval timer, i.e. a timer created by evaluating any of the functions <c>apply_interval/4</c>, <c>send_interval/3</c>, and <c>send_interval/2</c>, is linked to the process towards which the timer performs its task. </p> <p>A one-shot timer, i.e. a timer created by evaluating any of the functions <c>apply_after/4</c>, <c>send_after/3</c>, <c>send_after/2</c>, <c>exit_after/3</c>, <c>exit_after/2</c>, <c>kill_after/2</c>, and <c>kill_after/1</c> 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 <c>cancel/1</c>.</p> </section> </erlref>