Class NonBlockingReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable
    Direct Known Subclasses:
    NonBlockingPumpReader, NonBlockingReaderImpl

    public abstract class NonBlockingReader
    extends java.io.Reader
    A reader that provides non-blocking read operations.

    The NonBlockingReader class extends the standard Reader class to provide non-blocking read operations. Unlike standard readers, which block until data is available or the end of the stream is reached, non-blocking readers can be configured to return immediately or after a specified timeout if no data is available.

    This class is particularly useful for terminal applications that need to perform other tasks while waiting for user input, or that need to implement features like input timeouts or polling.

    The class defines two special return values:

    • EOF (-1) - Indicates that the end of the stream has been reached
    • READ_EXPIRED (-2) - Indicates that the read operation timed out

    Implementations of this class typically use a separate thread to handle blocking I/O operations, allowing the main thread to continue execution. The shutdown() method can be used to terminate this background thread when it is no longer needed.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int EOF  
      static int READ_EXPIRED  
      • Fields inherited from class java.io.Reader

        lock
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      int available()  
      int peek​(long timeout)
      Peeks to see if there is a byte waiting in the input stream without actually consuming the byte.
      int read()  
      int read​(char[] b, int off, int len)
      This version of read() is very specific to jline's purposes, it will always always return a single byte at a time, rather than filling the entire buffer.
      int read​(long timeout)
      Attempts to read a character from the input stream for a specific period of time.
      protected abstract int read​(long timeout, boolean isPeek)
      Attempts to read a character from the input stream for a specific period of time.
      int readBuffered​(char[] b)  
      abstract int readBuffered​(char[] b, int off, int len, long timeout)  
      int readBuffered​(char[] b, long timeout)  
      void shutdown()
      Shuts down the thread that is handling blocking I/O.
      • Methods inherited from class java.io.Reader

        close, mark, markSupported, nullReader, read, read, ready, reset, skip, transferTo
      • Methods inherited from class java.lang.Object

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

      • NonBlockingReader

        public NonBlockingReader()
    • Method Detail

      • shutdown

        public void shutdown()
        Shuts down the thread that is handling blocking I/O.

        This method terminates the background thread that is used to handle blocking I/O operations. This allows the application to clean up resources and prevent thread leaks when the reader is no longer needed.

        Note that if the thread is currently blocked waiting for I/O, it will not actually shut down until the I/O is received or the thread is interrupted. In some implementations, this method may interrupt the thread to force it to shut down immediately.

        After calling this method, the reader should not be used anymore, as subsequent read operations may fail or block indefinitely.

      • read

        public int read()
                 throws java.io.IOException
        Overrides:
        read in class java.io.Reader
        Throws:
        java.io.IOException
      • peek

        public int peek​(long timeout)
                 throws java.io.IOException
        Peeks to see if there is a byte waiting in the input stream without actually consuming the byte.
        Parameters:
        timeout - The amount of time to wait, 0 == forever
        Returns:
        -1 on eof, -2 if the timeout expired with no available input or the character that was read (without consuming it).
        Throws:
        java.io.IOException - if anything wrong happens
      • read

        public int read​(long timeout)
                 throws java.io.IOException
        Attempts to read a character from the input stream for a specific period of time.
        Parameters:
        timeout - The amount of time to wait for the character
        Returns:
        The character read, -1 if EOF is reached, or -2 if the read timed out.
        Throws:
        java.io.IOException - if anything wrong happens
      • read

        public int read​(char[] b,
                        int off,
                        int len)
                 throws java.io.IOException
        This version of read() is very specific to jline's purposes, it will always always return a single byte at a time, rather than filling the entire buffer.
        Specified by:
        read in class java.io.Reader
        Parameters:
        b - the buffer
        off - the offset in the buffer
        len - the maximum number of chars to read
        Throws:
        java.io.IOException - if anything wrong happens
      • readBuffered

        public int readBuffered​(char[] b)
                         throws java.io.IOException
        Throws:
        java.io.IOException
      • readBuffered

        public int readBuffered​(char[] b,
                                long timeout)
                         throws java.io.IOException
        Throws:
        java.io.IOException
      • readBuffered

        public abstract int readBuffered​(char[] b,
                                         int off,
                                         int len,
                                         long timeout)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • available

        public int available()
      • read

        protected abstract int read​(long timeout,
                                    boolean isPeek)
                             throws java.io.IOException
        Attempts to read a character from the input stream for a specific period of time.
        Parameters:
        timeout - The amount of time to wait for the character
        isPeek - trueif the character read must not be consumed
        Returns:
        The character read, -1 if EOF is reached, or -2 if the read timed out.
        Throws:
        java.io.IOException - if anything wrong happens