File: timer.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (448 lines) | stat: -rw-r--r-- 11,579 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>timer</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>timer</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
timer
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Timer Functions

</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

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


</DIV>

<H3>EXPORTS</H3>

<P><A NAME="start/0"><STRONG><CODE>start() -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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.
        
</DIV>

<P><A NAME="apply_after/4"><STRONG><CODE>apply_after(Time, Module, Function, Arguments) -&#62; {ok, Tref} | 
{error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time = integer() in Milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Module = Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arguments = [term()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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>.
        
</DIV>

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

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<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>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

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

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<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>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="apply_interval/4"><STRONG><CODE>apply_interval(Time, Module, Function, Arguments) -&#62; {ok, TRef} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time = integer() in milliseconds</CODE></STRONG><BR>
<STRONG><CODE>Module = Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arguments = [term()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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>.
        
</DIV>

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

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<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>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="cancel/1"><STRONG><CODE>cancel(TRef) -&#62; {ok, cancel} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<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.
        
</DIV>

<P><A NAME="sleep/1"><STRONG><CODE>sleep(Time) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time = integer() in milliseconds</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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.
        
</DIV>

<P><A NAME="tc/3"><STRONG><CODE>tc(Module, Function, Arguments) -&#62; {Time, Value}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<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>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<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.
        
</DIV>

<P><A NAME="now_diff/2"><STRONG><CODE>now_diff(T2, T1) -&#62; Tdiff
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>T1 = T2 = {MegaSecs, Secs, MicroSecs}</CODE></STRONG><BR>
<STRONG><CODE>Tdiff = MegaSecs = Secs = MicroSecs = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Calculates the time difference <CODE>Tdiff = T2 - T1</CODE> in
         <STRONG>microseconds</STRONG>, where <CODE>T1</CODE> and <CODE>T2</CODE> probably
         are timestamp tuples returned from <CODE>erlang:now/0</CODE>.

</DIV>

<P><A NAME="seconds/1"><STRONG><CODE>seconds(Seconds) -&#62; Milliseconds</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the number of milliseconds in <CODE>Seconds</CODE>.
        
</DIV>

<P><A NAME="minutes/1"><STRONG><CODE>minutes(Minutes) -&#62; Milliseconds</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Return the number of milliseconds in <CODE>Minutes</CODE>.
        
</DIV>

<P><A NAME="hours/1"><STRONG><CODE>hours(Hours) -&#62; Milliseconds</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the number of milliseconds in <CODE>Hours</CODE>.
        
</DIV>

<P><A NAME="hms/3"><STRONG><CODE>hms(Hours, Minutes, Seconds) -&#62; Milliseconds
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the number of milliseconds in <CODE>Hours + Minutes +
         Seconds</CODE>.
        
</DIV>

<H3>Examples</H3>
<DIV CLASS=REFBODY>

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

</DIV>

<H3>WARNING</H3>
<DIV CLASS=REFBODY>

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

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
 Sebastian Strollo - support@erlang.ericsson.se<BR>
 Dan Gudmundsson - support@erlang.ericsson.se<BR>
 Peter Hgfeldt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>