File: timer.html

package info (click to toggle)
erlang-doc-html 1%3A8.0-1
links: PTS
area: main
in suites: woody
size: 18,028 kB
ctags: 7,419
sloc: perl: 1,841; ansic: 323; erlang: 155
file content (258 lines) | stat: -rw-r--r-- 9,922 bytes
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>timer</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>


<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>timer</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
timer</UL>
<H3>MODULE SUMMARY</H3>
<UL>
Timer Functions
</UL>
<H3>DESCRIPTION</H3>
<UL>
<P>This module provides useful functions related to time. Unless otherwise
stated, time is always measured in <CODE>milliseconds</CODE>. All
timer functions return immediately, regardless of work carried
out by another process. 

<P>Successful evaluations of the timer functions yield return values
containing a timer reference, denoted <CODE>TRef</CODE> below. By using 
<CODE>cancel/1</CODE>, the returned reference can be used to cancel any
requested action. A <CODE>TRef</CODE> is an Erlang term, the contents
of which must not be altered.

<P>The timeouts are not exact, but should be <CODE>at least</CODE> as long
as requested.

</UL>
<H3>EXPORTS</H3>
<P><A NAME="start%0"><STRONG><CODE>start() -&#62; ok</CODE></STRONG></A><BR>
<UL>
<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 <CODE>kernel</CODE> for this.
        </UL>
<P><A NAME="apply_after%4"><STRONG><CODE>apply_after(Time, Module, Function, Arguments) -&#62; {ok, Tref} | 
{error, Reason}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time = integer() in Milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Module = Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arguments = [term()]</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Evaluates <CODE>apply(M, F, A)</CODE> after <CODE>Time</CODE> amount of time
         has elapsed. Returns <CODE>{ok, TRef}</CODE>, or <CODE>{error, Reason}</CODE>.
        </UL>
<P><A NAME="send_after%3"><STRONG><CODE>send_after(Time, Pid, Message) -&#62; {ok, TRef} | {error,Reason}
</CODE></STRONG></A><BR>
<A NAME="send_after%2"><STRONG><CODE>send_after(Time, Message) -&#62; {ok, TRef} | {error,Reason}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time = integer() in Milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid() | atom()</CODE></STRONG><BR>
<STRONG><CODE>Message = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok, TRef} | {error, Reason}</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>     <P><DL>
<DT><CODE>send_after/3</CODE></DT>
<DD>Evaluates <CODE>Pid ! Message</CODE> after <CODE>Time</CODE> amount
         of time has elapsed. (<CODE>Pid</CODE> can also be an atom of a 
         registered name.) Returns <CODE>{ok, TRef}</CODE>, or 
         <CODE>{error, Reason}</CODE>.
         <BR>
</DD>
<DT><CODE>send_after/2</CODE></DT>
<DD>Same as <CODE>send_after(Time, self(), Message)</CODE>.
         <BR>
</DD>
</DL>
</UL>
<P><A NAME="exit_after%3"><STRONG><CODE>exit_after(Time, Pid, Reason1) -&#62; {ok, TRef} | {error,Reason2}</CODE></STRONG></A><BR>
<A NAME="exit_after%2"><STRONG><CODE>exit_after(Time, Reason1) -&#62; {ok, TRef} | {error,Reason2}</CODE></STRONG></A><BR>
<A NAME="kill_after%2"><STRONG><CODE>kill_after(Time, Pid)-&#62; {ok, TRef} | {error,Reason2}</CODE></STRONG></A><BR>
<A NAME="kill_after%1"><STRONG><CODE>kill_after(Time) -&#62; {ok, TRef} | {error,Reason2}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time = integer() in milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid() | atom()</CODE></STRONG><BR>
<STRONG><CODE>Reason1 = Reason2 = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>     <P><DL>
<DT><CODE>exit_after/3</CODE></DT>
<DD>Send an exit signal with reason <CODE>Reason1</CODE> to Pid 
         <CODE>Pid</CODE>. Returns <CODE>{ok, TRef}</CODE>, or 
         <CODE>{error, Reason2}</CODE>.
         <BR>
</DD>
<DT><CODE>exit_after/2</CODE></DT>
<DD>Same as <CODE>exit_after(Time, self(), Reason1)</CODE>. 
         <BR>
</DD>
<DT><CODE>kill_after/2</CODE></DT>
<DD>Same as <CODE>exit_after(Time, Pid, kill)</CODE>. 
         <BR>
</DD>
<DT><CODE>kill_after/1</CODE></DT>
<DD>Same as <CODE>exit_after(Time, self(), kill)</CODE>. 
         <BR>
</DD>
</DL>
</UL>
<P><A NAME="apply_interval%4"><STRONG><CODE>apply_interval(Time, Module, Function, Arguments) -&#62; {ok, TRef} | {error, Reason}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time = integer() in milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Module = Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arguments = [term()]</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Evaluates <CODE>apply(Module, Function, Arguments)</CODE> repeatedly at
         intervals of <CODE>Time</CODE>. Returns <CODE>{ok, TRef}</CODE>, or 
         <CODE>{error, Reason}</CODE>.
        </UL>
<P><A NAME="send_interval%3"><STRONG><CODE>send_interval(Time, Pid, Message) -&#62; {ok, TRef} | {error, Reason}
</CODE></STRONG></A><BR>
<A NAME="send_interval%2"><STRONG><CODE>send_interval(Time, Message) -&#62; {ok, TRef} | {error, Reason}
</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time = integer() in milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid() | atom()</CODE></STRONG><BR>
<STRONG><CODE>Message = term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>     <P><DL>
<DT><CODE>send_interval/3</CODE></DT>
<DD>Evaluates <CODE>Pid ! Message</CODE> repeatedly after <CODE>Time</CODE>
         amount of time has elapsed. (<CODE>Pid</CODE> can also be an atom of
         a registered name.) Returns <CODE>{ok, TRef}</CODE> or 
         <CODE>{error, Reason}</CODE>.
         <BR>
</DD>
<DT><CODE>send_interval/2</CODE></DT>
<DD>Same as <CODE>send_interval(Time, self(), Message)</CODE>.
         <BR>
</DD>
</DL>
</UL>
<P><A NAME="cancel%1"><STRONG><CODE>cancel(TRef) -&#62; {ok, cancel} | {error, Reason}</CODE></STRONG></A><BR>
<UL>
<P>Cancels a previously requested timeout. <CODE>TRef</CODE> is a unique 
         timer reference returned by the timer function in question. Returns
         <CODE>{ok, cancel}</CODE>, or <CODE>{error, Reason}</CODE> when <CODE>TRef</CODE>
         is not a timer reference.
        </UL>
<P><A NAME="sleep%1"><STRONG><CODE>sleep(Time) -&#62; ok</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Time = integer() in milliseconds</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Suspends the process calling this function for <CODE>Time</CODE> amount
         of milliseconds and then returns <CODE>ok</CODE>. Naturally, this 
         function does <STRONG>not</STRONG> return immediately.
        </UL>
<P><A NAME="tc%3"><STRONG><CODE>tc(Module, Function, Arguments) -&#62; {Time, Value}
</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Module = Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arguments = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Time = integer() in microseconds</CODE></STRONG><BR>
<STRONG><CODE>Value = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Evaluates <CODE>apply(Module, Function, Arguments)</CODE> and measures
         the elapsed real time. Returns <CODE>{Time, Value}</CODE>, where 
         <CODE>Time</CODE> is the elapsed real time in <STRONG>microseconds</STRONG>,
         and <CODE>Value</CODE> is what is returned from the apply.
        </UL>
<P><A NAME="seconds%1"><STRONG><CODE>seconds(Seconds) -&#62; Milliseconds</CODE></STRONG></A><BR>
<UL>
<P>Returns the number of milliseconds in <CODE>Seconds</CODE>.
        </UL>
<P><A NAME="minutes%1"><STRONG><CODE>minutes(Minutes) -&#62; Milliseconds</CODE></STRONG></A><BR>
<UL>
<P>Return the number of milliseconds in <CODE>Minutes</CODE>.
        </UL>
<P><A NAME="hours%1"><STRONG><CODE>hours(Hours) -&#62; Milliseconds</CODE></STRONG></A><BR>
<UL>
<P>Returns the number of milliseconds in <CODE>Hours</CODE>.
        </UL>
<P><A NAME="hms%3"><STRONG><CODE>hms(Hours, Minutes, Seconds) -&#62; Milliseconds
</CODE></STRONG></A><BR>
<UL>
<P>Returns the number of milliseconds in <CODE>Hours + Minutes +
         Seconds</CODE>.
        </UL>
<H3>Examples</H3>
<UL>
<P>This example illustrates how to print out &#34;Hello World!&#34; in 5 seconds:
<P> <PRE>      1&#62; timer:apply_after(5000, io, format, [&#34;~nHello World!~n&#34;, []]).
      {ok,TRef}
      Hello World!
      2&#62; 
    </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.<PRE>      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),
      ...
    </PRE></UL>
<H3>WARNING</H3>
<UL>
<P>A timer can always be removed by calling <CODE>cancel/1</CODE>.

<P>An interval timer, i.e. a timer created by evaluating any of the 
functions <CODE>apply_interval/4</CODE>, <CODE>send_interval/3</CODE>, and 
<CODE>send_interval/2</CODE>, is linked to the process towards which
the timer performs its task.

<P>A one-shot timer, i.e. a timer created by evaluating any of the
functions <CODE>apply_after/4</CODE>, <CODE>send_after/3</CODE>, 
<CODE>send_after/2</CODE>, <CODE>exit_after/3</CODE>, <CODE>exit_after/2</CODE>, 
<CODE>kill_after/2</CODE>, and <CODE>kill_after/1</CODE> 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 <CODE>cancel/1</CODE>.
</UL>
<H3>AUTHORS</H3>
<UL>
 Sebastian Strollo - support@erlang.ericsson.se<BR>
 Dan Gudmundsson - support@erlang.ericsson.se<BR>
 Peter H&#246;gfeldt - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright &copy; 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>