Package okio

Class Timeout

  • Direct Known Subclasses:
    AsyncTimeout, ForwardingTimeout

    public class Timeout
    extends java.lang.Object
    A policy on how much time to spend on a task before giving up. When a task times out, it is left in an unspecified state and should be abandoned. For example, if reading from a source times out, that source should be closed and the read should be retried later. If writing to a sink times out, the same rules apply: close the sink and retry later.

    Timeouts and Deadlines

    This class offers two complementary controls to define a timeout policy.

    Timeouts specify the maximum time to wait for a single operation to complete. Timeouts are typically used to detect problems like network partitions. For example, if a remote peer doesn't return any data for ten seconds, we may assume that the peer is unavailable.

    Deadlines specify the maximum time to spend on a job, composed of one or more operations. Use deadlines to set an upper bound on the time invested on a job. For example, a battery-conscious app may limit how much time it spends pre-loading content.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Timeout NONE
      An empty timeout that neither tracks nor detects timeouts.
    • Constructor Summary

      Constructors 
      Constructor Description
      Timeout()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Timeout clearDeadline()
      Clears the deadline.
      Timeout clearTimeout()
      Clears the timeout.
      Timeout deadline​(long duration, java.util.concurrent.TimeUnit unit)
      Set a deadline of now plus duration time.
      long deadlineNanoTime()
      Returns the nano time when the deadline will be reached.
      Timeout deadlineNanoTime​(long deadlineNanoTime)
      Sets the nano time when the deadline will be reached.
      boolean hasDeadline()
      Returns true if a deadline is enabled.
      void throwIfReached()
      Throws an InterruptedIOException if the deadline has been reached or if the current thread has been interrupted.
      Timeout timeout​(long timeout, java.util.concurrent.TimeUnit unit)
      Wait at most timeout time before aborting an operation.
      long timeoutNanos()
      Returns the timeout in nanoseconds, or 0 for no timeout.
      void waitUntilNotified​(java.lang.Object monitor)
      Waits on monitor until it is notified.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NONE

        public static final Timeout NONE
        An empty timeout that neither tracks nor detects timeouts. Use this when timeouts aren't necessary, such as in implementations whose operations do not block.
    • Constructor Detail

      • Timeout

        public Timeout()
    • Method Detail

      • timeout

        public Timeout timeout​(long timeout,
                               java.util.concurrent.TimeUnit unit)
        Wait at most timeout time before aborting an operation. Using a per-operation timeout means that as long as forward progress is being made, no sequence of operations will fail.

        If timeout == 0, operations will run indefinitely. (Operating system timeouts may still apply.)

      • timeoutNanos

        public long timeoutNanos()
        Returns the timeout in nanoseconds, or 0 for no timeout.
      • hasDeadline

        public boolean hasDeadline()
        Returns true if a deadline is enabled.
      • deadlineNanoTime

        public long deadlineNanoTime()
        Returns the nano time when the deadline will be reached.
        Throws:
        java.lang.IllegalStateException - if no deadline is set.
      • deadlineNanoTime

        public Timeout deadlineNanoTime​(long deadlineNanoTime)
        Sets the nano time when the deadline will be reached. All operations must complete before this time. Use a deadline to set a maximum bound on the time spent on a sequence of operations.
      • deadline

        public final Timeout deadline​(long duration,
                                      java.util.concurrent.TimeUnit unit)
        Set a deadline of now plus duration time.
      • clearTimeout

        public Timeout clearTimeout()
        Clears the timeout. Operating system timeouts may still apply.
      • clearDeadline

        public Timeout clearDeadline()
        Clears the deadline.
      • throwIfReached

        public void throwIfReached()
                            throws java.io.IOException
        Throws an InterruptedIOException if the deadline has been reached or if the current thread has been interrupted. This method doesn't detect timeouts; that should be implemented to asynchronously abort an in-progress operation.
        Throws:
        java.io.IOException
      • waitUntilNotified

        public final void waitUntilNotified​(java.lang.Object monitor)
                                     throws java.io.InterruptedIOException
        Waits on monitor until it is notified. Throws InterruptedIOException if either the thread is interrupted or if this timeout elapses before monitor is notified. The caller must be synchronized on monitor.

        Here's a sample class that uses waitUntilNotified() to await a specific state. Note that the call is made within a loop to avoid unnecessary waiting and to mitigate spurious notifications.

        
        
           class Dice {
             Random random = new Random();
             int latestTotal;
        
             public synchronized void roll() {
               latestTotal = 2 + random.nextInt(6) + random.nextInt(6);
               System.out.println("Rolled " + latestTotal);
               notifyAll();
             }
        
             public void rollAtFixedRate(int period, TimeUnit timeUnit) {
               Executors.newScheduledThreadPool(0).scheduleAtFixedRate(new Runnable() {
                 public void run() {
                   roll();
                  }
               }, 0, period, timeUnit);
             }
        
             public synchronized void awaitTotal(Timeout timeout, int total)
                 throws InterruptedIOException {
               while (latestTotal != total) {
                 timeout.waitUntilNotified(this);
               }
             }
           }
         
        Throws:
        java.io.InterruptedIOException