Deadline.scala

/*
 * Scala (https://www.scala-lang.org)
 *
 * Copyright EPFL and Lightbend, Inc. dba Akka
 *
 * Licensed under Apache License 2.0
 * (http://www.apache.org/licenses/LICENSE-2.0).
 *
 * See the NOTICE file distributed with this work for
 * additional information regarding copyright ownership.
 */

package scala.concurrent.duration

import scala.language.`2.13`

/** This class stores a deadline, as obtained via `Deadline.now` or the
 *  duration DSL:
 *
 *  ```scala sc:compile
 *  import scala.concurrent.duration.*
 *  3.seconds.fromNow
 *  ```
 *
 *  Its main purpose is to manage repeated attempts to achieve something (like
 *  awaiting a condition) by offering the methods `hasTimeLeft` and `timeLeft`.  All
 *  durations are measured according to `System.nanoTime`; this
 *  does not take into account changes to the system clock (such as leap
 *  seconds).
 */
case class Deadline private (time: FiniteDuration) extends Ordered[Deadline] {
  /** Returns a deadline advanced (i.e., moved into the future) by the given duration.
   *
   *  @param other the duration by which to advance this deadline
   */
  def +(other: FiniteDuration): Deadline = copy(time = time + other)
  /** Returns a deadline moved backwards (i.e., towards the past) by the given duration.
   *
   *  @param other the duration by which to move this deadline backwards
   */
  def -(other: FiniteDuration): Deadline = copy(time = time - other)
  /** Calculates time difference between this and the other deadline, where the result is directed (i.e., may be negative).
   *
   *  @param other the deadline to subtract from this deadline, yielding a directed duration
   */
  def -(other: Deadline): FiniteDuration = time - other.time
  /** Calculates time difference between this duration and now; the result is negative if the deadline has passed.
   *
   *  ***Note that on some systems this operation is costly because it entails a system call.***
   *  Checks `System.nanoTime` for your platform.
   *
   *  @return the duration remaining until this deadline, negative if the deadline has passed
   */
  def timeLeft: FiniteDuration = this - Deadline.now
  /** Determine whether the deadline still lies in the future at the point where this method is called.
   *
   *  ***Note that on some systems this operation is costly because it entails a system call.***
   *  Checks `System.nanoTime` for your platform.
   *
   *  @return `true` if the deadline has not yet passed, `false` otherwise
   */
  def hasTimeLeft(): Boolean = !isOverdue()
  /** Determine whether the deadline lies in the past at the point where this method is called.
   *
   *  ***Note that on some systems this operation is costly because it entails a system call.***
   *  Checks `System.nanoTime` for your platform.
   *
   *  @return `true` if the deadline has passed, `false` otherwise
   */
  def isOverdue(): Boolean = (time.toNanos - System.nanoTime()) < 0
  /** The natural ordering for deadline is determined by the natural order of the underlying (finite) duration.
   *
   *  @param other the deadline to compare against
   *  @return a negative value if this deadline is earlier than `other`, zero if they are equal, or a positive value if this deadline is later
   */
  def compare(other: Deadline): Int = time compare other.time
}

object Deadline {
  /** Constructs a deadline due exactly at the point where this method is called. Useful for then
   *  advancing it to obtain a future deadline, or for sampling the current time exactly once and
   *  then comparing it to multiple deadlines (using subtraction).
   */
  def now: Deadline = Deadline(Duration(System.nanoTime, NANOSECONDS))

  /** The natural ordering for deadline is determined by the natural order of the underlying (finite) duration. */
  implicit object DeadlineIsOrdered extends Ordering[Deadline] {
    def compare(a: Deadline, b: Deadline): Int = a compare b
  }

}