public interface ByteSink
Bytes are written to the sink through method write(ByteBuffer).
The sink must be closed after use.
The writer should also call error(Exception) to indicate that the byte sequence is corrupt.
In general, a ByteSink is not thread-safe.
In general, concurrent pending actions are not allowed. Particularly, close() cannot be invoked while a write() is pending.
Async<Void> write(ByteBuffer bb)
If this action fails, the sink should be considered in an error state, and it should be closed immediately.
The ownership of `bb` is transferred to the sink. The sink should treat the content of `bb` as read-only.
CAUTION: since ByteBuffer is stateful (even for methods like ByteBuffer.get()),
a new ByteBuffer must be created for each write() action.
The caller may create a view of a shared ByteBuffer through
ByteBuffer.asReadOnlyBuffer().
The app should wait for this write() action to complete before it calls another method on this sink.
Async<Void> error(Exception error)
If the data producer encounters an error, it should set the sink to an error state, so that the situation is not confused with a graceful termination of writing.
For example, a server app calculates data and writes them to an http response sink.
If an exception occurs in the calculation, the app should call sink.error(),
so that the client can know that the response body is corrupt.
If the sink is in an error state, it should be closed immediately.
This method can be called multiple times; only the first call is effective.
Async<Void> close()
If the sink is not in an error state, close() should flush all previously written data, and wait for the flushing to complete.
The close() action is important to finalize the writing process. If the close() action fails, it may indicate that the data are not reliably delivered to the destination.
This method can be called multiple times; only the first call is effective.