trait Timer[F[_]] extends AnyRef
Timer is a scheduler of tasks.
This is the purely functional equivalent of:
- Java's ScheduledExecutorService
- JavaScript's setTimeout.
It provides:
- the ability to get the current time
- thread / call-stack shifting
- ability to delay the execution of a task with a specified time duration
It does all of that in an F
monadic context that can suspend
side effects and is capable of asynchronous execution (e.g. IO).
This is NOT a type class, as it does not have the coherence requirement.
- Annotations
- @implicitNotFound( ... )
- Source
- Timer.scala
- Alphabetic
- By Inheritance
- Timer
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Abstract Value Members
-
abstract
def
clockMonotonic(unit: TimeUnit): F[Long]
Returns a monotonic clock measurement, if supported by the underlying platform.
Returns a monotonic clock measurement, if supported by the underlying platform.
This is the pure equivalent of Java's
System.nanoTime
, or ofCLOCK_MONOTONIC
from Linux'sclock_gettime()
.timer.clockMonotonic(NANOSECONDS)
The returned value can have nanoseconds resolution and represents the number of time units elapsed since some fixed but arbitrary origin time. Usually this is the Unix epoch, but that's not a guarantee, as due to the limits of
Long
this will overflow in the future (263 is about 292 years in nanoseconds) and the implementation reserves the right to change the origin.The return value should not be considered related to wall-clock time, the primary use-case being to take time measurements and compute differences between such values, for example in order to measure the time it took to execute a task.
As a matter of implementation detail, the default
Timer[IO]
implementation usesSystem.nanoTime
and the JVM will useCLOCK_MONOTONIC
when available, instead ofCLOCK_REALTIME
(seeclock_gettime()
on Linux) and it is up to the underlying platform to implement it correctly.And be warned, there are platforms that don't have a correct implementation of
CLOCK_MONOTONIC
. For example at the moment of writing there is no standard way for such a clock on top of JavaScript and the situation isn't so clear cut for the JVM either, see:- bug report
- concurrency-interest discussion on the X86 tsc register
The JVM tries to do the right thing and at worst the resolution and behavior will be that of
System.currentTimeMillis
.The recommendation is to use this monotonic clock when doing measurements of execution time, or if you value monotonically increasing values more than a correspondence to wall-time, or otherwise prefer clockRealTime.
-
abstract
def
clockRealTime(unit: TimeUnit): F[Long]
Returns the current time, as a Unix timestamp (number of time units since the Unix epoch), suspended in
F[_]
.Returns the current time, as a Unix timestamp (number of time units since the Unix epoch), suspended in
F[_]
.This is the pure equivalent of Java's
System.currentTimeMillis
, or ofCLOCK_REALTIME
from Linux'sclock_gettime()
.The provided
TimeUnit
determines the time unit of the output, its precision, but not necessarily its resolution, which is implementation dependent. For example this will return the number of milliseconds since the epoch:import scala.concurrent.duration.MILLISECONDS timer.clockRealTime(MILLISECONDS)
N.B. the resolution is limited by the underlying implementation and by the underlying CPU and OS. If the implementation uses
System.currentTimeMillis
, then it can't have a better resolution than 1 millisecond, plus depending on underlying runtime (e.g. Node.js) it might return multiples of 10 milliseconds or more.See clockMonotonic, for fetching a monotonic value that may be better suited for doing time measurements.
-
abstract
def
shift: F[Unit]
Asynchronous boundary described as an effectful
F[_]
that can be used inflatMap
chains to "shift" the continuation of the run-loop to another thread or call stack.Asynchronous boundary described as an effectful
F[_]
that can be used inflatMap
chains to "shift" the continuation of the run-loop to another thread or call stack.This is the Async.shift operation, without the need for an
ExecutionContext
taken as a parameter.This
shift
operation can usually be derived fromsleep
:timer.shift <-> timer.sleep(Duration.Zero)
-
abstract
def
sleep(duration: FiniteDuration): F[Unit]
Creates a new task that will sleep for the given duration, emitting a tick when that time span is over.
Creates a new task that will sleep for the given duration, emitting a tick when that time span is over.
As an example on evaluation this will print "Hello!" after 3 seconds:
import cats.effect._ import scala.concurrent.duration._ Timer[IO].sleep(3.seconds).flatMap { _ => IO(println("Hello!")) }
Note that
sleep
is required to introduce an asynchronous boundary, even if the providedtimespan
is less or equal to zero.
Concrete Value Members
-
final
def
!=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
##(): Int
- Definition Classes
- AnyRef → Any
-
final
def
==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
-
def
clone(): AnyRef
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @native() @throws( ... )
-
final
def
eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
def
equals(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
def
finalize(): Unit
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( classOf[java.lang.Throwable] )
-
final
def
getClass(): Class[_]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
-
def
hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
-
final
def
isInstanceOf[T0]: Boolean
- Definition Classes
- Any
-
final
def
ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
final
def
notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
-
final
def
synchronized[T0](arg0: ⇒ T0): T0
- Definition Classes
- AnyRef
-
def
toString(): String
- Definition Classes
- AnyRef → Any
-
final
def
wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @throws( ... )
This is the API documentation for the cats-effect library.
See the cats.effect package for a quick overview.
Links
Canonical documentation links:
Related Cats links (the core):