AsyncOutputStream

package saker.util.io

public class AsyncOutputStream extends OutputStream implements ByteSink

saker.util.io.AsyncOutputStream

java.io.OutputStream

java.lang.Object

java.io.Closeable

java.lang.AutoCloseable

java.io.Flushable

saker.util.io.ByteSink

OutputStream implementation that takes write requests and executes the writing to a subject stream asynchronously.

An instance of this class is created for a given output stream. The class will spawn its own thread that executes the write operations to the given stream.

When a write request is issued to this stream, it will take the bytes from the argument, and copy them to an internal buffer. The internal buffer is asynchronously flushed to the subject output stream on the flusher thread.

Any exceptions which are thrown by the subject stream may be reported asynchronously in any future write, flush, or close operations. Therefore callers should be noted, that an exception thrown from a method of this class may not be directly related to the actually called method. Any exception occurring on the flusher thread will be rethrown as AsyncOutputIOException.

When the async output stream is closed, or flush() is called, all the pending write operations will be finished before that method returns. Closing this stream will shut down the flusher thread, and close the subject stream as well.

Using this class can be advantageous when the subject stream may block during write operations, and the caller could proceed with its work instead of waiting for I/O.

If the callers fail to properly close this stream, the flushing thread will automatically quit when the AsyncOutputStream instance is garbage collected. (The flushing stream is also a daemon thread.)

The flushing stream is started with a low priority, therefore longer delays can occurr if the CPU is doing more important work.

Nested types

public static class	AsyncOutputIOException Exception class that is signaling an IOException that occurred in an other time than the current call.

Fields

protected final ReentrantLock	lock

Constructors

public	AsyncOutputStream(OutputStream out) Creates a new instance for the given stream.
public	AsyncOutputStream(OutputStream out, ThreadFactory threadfactory) Creates a new instance that uses the given thread factory.

Methods

public void	close() Closes this output stream and releases any system resources associated with this stream.
public void	deliver() Delivers any pending I/O operations to the underlying stream.
public void	exit() Sends a quit signal to the flushing thread, and will consider this stream closed for further operations.
public void	flush() Flushes this output stream and forces any buffered output bytes to be written out.
public void	write(int b) Writes the specified byte to this output stream.
public void	write(ByteArrayRegion buf) Writes the bytes contained in the argument byte array to the byte sink.
public void	write(byte[] b) Writes `b.length` bytes from the specified byte array to this output stream.
public void	write(byte[] b, int off, int len) Writes `len` bytes from the specified byte array starting at offset `off` to this output stream.

Inherited methods
From: ByteSink readFrom
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

protected final ReentrantLock lock

public AsyncOutputStream(OutputStream out) throws NullPointerException

Creates a new instance for the given stream.

outThe stream.

NullPointerExceptionIf the stream is null.

public AsyncOutputStream(OutputStream out, ThreadFactory threadfactory) throws NullPointerException

Creates a new instance that uses the given thread factory.

The specified thread factory will be used to create the asynchronously flushing thread. The thread factory should set if the thread is daemon and set its priority.

outThe output stream.

threadfactoryThe thread factory. May be null in which case a new daemon thread with minimum priority is created.

NullPointerExceptionIf the output stream is null.

saker.util 0.8.2

public void close() throws IOException

Overridden from: OutputStream

Closes this output stream and releases any system resources associated with this stream. The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened.

The close method of OutputStream does nothing.

IOExceptionif an I/O error occurs.

public void deliver() throws IOException, InterruptedIOException

Delivers any pending I/O operations to the underlying stream.

This method will not flush() the underlying stream, only waits for all pending operations to finish.

IOExceptionIn case of I/O error.

InterruptedIOExceptionIf the waiting for the delivering was interrupted, or the underlying stream threw such an exception.

public void exit()

Sends a quit signal to the flushing thread, and will consider this stream closed for further operations.

This method will send a quit signal to the flusher thread, prompting it to finish. This method doesn't close or flush the subject stream. Any further I/O methods to this stream will report it as closed.

Similar to deliver(), all pending operations will be waited.

public void flush() throws IOException

Flushes this output stream and forces any buffered output bytes to be written out.The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination.

If the intended destination of this stream is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive.

The flush method of OutputStream does nothing.

This method also waits for the flushing to be done on the flusher thread.

IOExceptionif an I/O error occurs.

public void write(int b) throws IOException

Overridden from: OutputStream

Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

Subclasses of OutputStream must provide an implementation for this method.

bthe byte.

IOExceptionif an I/O error occurs. In particular, an IOException may be thrown if the output stream has been closed.

public void write(ByteArrayRegion buf) throws IOException, NullPointerException

Overridden from: ByteSink

Writes the bytes contained in the argument byte array to the byte sink.

This method works similarly to OutputStream.write(byte[], int, int).

bufThe bytes to write.

IOExceptionIn case of I/O error.

NullPointerExceptionIf the argument is null.

public void write(byte[] b) throws IOException

Overridden from: OutputStream

Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).

bthe data.

IOExceptionif an I/O error occurs.

OutputStream.write(byte[], int, int)

public void write(byte[] b, int off, int len) throws IOException

Overridden from: OutputStream

Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

The write method of OutputStream calls the write method of one argument on each of the bytes to be written out. Subclasses are encouraged to override this method and provide a more efficient implementation.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

bthe data.

offthe start offset in the data.

lenthe number of bytes to write.

IOExceptionif an I/O error occurs. In particular, an IOException is thrown if the output stream is closed.