Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
timer(3)		   Erlang Module Definition		      timer(3)

NAME
       timer - Timer Functions

DESCRIPTION
       This module provides useful functions related to	time. Unless otherwise
       stated, time is always measured in milliseconds.	 All  timer  functions
       return immediately, regardless of work carried out by another process.

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

       The timeouts are	not exact, but should be  at  least  as	 long  as  re-
       quested.

DATA TYPES
       time() =	integer() >= 0

	      Time in milliseconds.

       tref()

	      A	timer reference.

EXPORTS
       start() -> ok

	      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 sys-
	      tem the server should be started explicitly.  Use	 configuration
	      parameters for kernel for	this.

       apply_after(Time, Module, Function, Arguments) ->
		      {ok, TRef} | {error, Reason}

	      Types:

		 Time =	time()
		 Module	= module()
		 Function = atom()
		 Arguments = [term()]
		 TRef =	tref()
		 Reason	= term()

	      Evaluates	 apply(Module,	Function, Arguments) after Time	amount
	      of time has elapsed. Returns {ok,	TRef}, or {error, Reason}.

       send_after(Time,	Message) -> {ok, TRef} | {error, Reason}

       send_after(Time,	Pid, Message) -> {ok, TRef} | {error, Reason}

	      Types:

		 Time =	time()
		 Pid = pid() | (RegName	:: atom())
		 Message = term()
		 TRef =	tref()
		 Reason	= term()

		send_after/3:
		  Evaluates Pid	!  Message  after  Time	 amount	 of  time  has
		  elapsed. (Pid	can also be an atom of a registered name.) Re-
		  turns	{ok, TRef}, or {error, Reason}.

		send_after/2:
		  Same as send_after(Time, self(), Message).

       kill_after(Time)	-> {ok,	TRef} |	{error,	Reason2}

       kill_after(Time,	Pid) ->	{ok, TRef} | {error, Reason2}

       exit_after(Time,	Reason1) -> {ok, TRef} | {error, Reason2}

       exit_after(Time,	Pid, Reason1) -> {ok, TRef} | {error, Reason2}

	      Types:

		 Time =	time()
		 Pid = pid() | (RegName	:: atom())
		 TRef =	tref()
		 Reason1 = Reason2 = term()

		exit_after/3:
		  Send an exit signal with reason Reason1 to Pid Pid.  Returns
		  {ok, TRef}, or {error, Reason2}.

		exit_after/2:
		  Same as exit_after(Time, self(), Reason1).

		kill_after/2:
		  Same as exit_after(Time, Pid,	kill).

		kill_after/1:
		  Same as exit_after(Time, self(), kill).

       apply_interval(Time, Module, Function, Arguments) ->
			 {ok, TRef} | {error, Reason}

	      Types:

		 Time =	time()
		 Module	= module()
		 Function = atom()
		 Arguments = [term()]
		 TRef =	tref()
		 Reason	= term()

	      Evaluates	 apply(Module,	Function, Arguments) repeatedly	at in-
	      tervals of Time. Returns {ok, TRef}, or {error, Reason}.

       send_interval(Time, Message) -> {ok, TRef} | {error, Reason}

       send_interval(Time, Pid,	Message) -> {ok, TRef} | {error, Reason}

	      Types:

		 Time =	time()
		 Pid = pid() | (RegName	:: atom())
		 Message = term()
		 TRef =	tref()
		 Reason	= term()

		send_interval/3:
		  Evaluates Pid	! Message repeatedly after Time	amount of time
		  has elapsed. (Pid can	also be	an atom	of a registered	name.)
		  Returns {ok, TRef} or	{error,	Reason}.

		send_interval/2:
		  Same as send_interval(Time, self(), Message).

       cancel(TRef) -> {ok, cancel} | {error, Reason}

	      Types:

		 TRef =	tref()
		 Reason	= term()

	      Cancels a	previously requested timeout. TRef is a	 unique	 timer
	      reference	 returned  by  the timer function in question. Returns
	      {ok, cancel}, or {error, Reason} when TRef is not	a timer	refer-
	      ence.

       sleep(Time) -> ok

	      Types:

		 Time =	timeout()

	      Suspends	the  process  calling this function for	Time amount of
	      milliseconds and then returns ok,	or suspend the process forever
	      if  Time is the atom infinity. Naturally,	this function does not
	      return immediately.

       tc(Fun) -> {Time, Value}

       tc(Fun, Arguments) -> {Time, Value}

       tc(Module, Function, Arguments) -> {Time, Value}

	      Types:

		 Module	= module()
		 Function = atom()
		 Arguments = [term()]
		 Time =	integer()
		   In microseconds
		 Value = term()

		tc/3:
		  Evaluates apply(Module, Function,  Arguments)	 and  measures
		  the elapsed real time	as reported by os:timestamp/0. Returns
		  {Time, Value}, where Time is the elapsed real	 time  in  mi-
		  croseconds, and Value	is what	is returned from the apply.

		tc/2:
		  Evaluates apply(Fun, Arguments). Otherwise works like	tc/3.

		tc/1:
		  Evaluates Fun(). Otherwise works like	tc/2.

       now_diff(T2, T1)	-> Tdiff

	      Types:

		 T1 = T2 = erlang:timestamp()
		 Tdiff = integer()
		   In microseconds

	      Calculates  the time difference Tdiff = T2 - T1 in microseconds,
	      where T1 and T2 probably are timestamp tuples returned from  er-
	      lang:now/0.

       seconds(Seconds)	-> MilliSeconds

	      Types:

		 Seconds = MilliSeconds	= integer() >= 0

	      Returns the number of milliseconds in Seconds.

       minutes(Minutes)	-> MilliSeconds

	      Types:

		 Minutes = MilliSeconds	= integer() >= 0

	      Return the number	of milliseconds	in Minutes.

       hours(Hours) -> MilliSeconds

	      Types:

		 Hours = MilliSeconds =	integer() >= 0

	      Returns the number of milliseconds in Hours.

       hms(Hours, Minutes, Seconds) -> MilliSeconds

	      Types:

		 Hours = Minutes = Seconds = MilliSeconds = integer() >= 0

	      Returns the number of milliseconds in Hours + Minutes + Seconds.

EXAMPLES
       This example illustrates	how to print out "Hello	World!"	in 5 seconds:

	     1>	timer:apply_after(5000,	io, format, ["~nHello World!~n", []]).
	     {ok,TRef}
	     Hello World!

       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.

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

WARNING
       A timer can always be removed by	calling	cancel/1.

       An  interval timer, i.e.	a timer	created	by evaluating any of the func-
       tions apply_interval/4, send_interval/3,	and send_interval/2, is	linked
       to the process towards which the	timer performs its task.

       A  one-shot  timer, i.e.	a timer	created	by evaluating any of the func-
       tions apply_after/4, send_after/3, send_after/2,	exit_after/3, exit_af-
       ter/2,  kill_after/2,  and  kill_after/1	 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 cancel/1.

Ericsson AB			  stdlib 2.4			      timer(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | EXAMPLES | WARNING

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=timer&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help