Provides the interfaces and classes for asynchronous (non-blocking) network I/O processing.

The server socket is managed by {@link com.webtide.wharf.io.ServerConnector} implementations.
For each new connection from a client, the following structures are created:

an {@link com.webtide.wharf.io.async.AsyncCoordinator}, which coordinates the activity between an {@link com.webtide.wharf.io.async.AsyncServerEndpoint} and an {@link com.webtide.wharf.io.async.AsyncInterpreter}
an {@link com.webtide.wharf.io.async.AsyncEndpoint}, which manages the physical I/O
an {@link com.webtide.wharf.io.async.AsyncInterpreter}, which deserializes bytes into protocol messages, calls application code, and serializes protocol messages to bytes

The flow of communication between the I/O system, the coordinator, the endpoint and the interpreter is the following, where === is the I/O system thread, --- is the read thread and ~~~ is the write thread.

Single read follows this flow:

    I/O System         AsyncCoordinator       AsyncServerEndpoint        AsyncInterpreter
        ===== readReady =====>
                                ----- readInto ---->
                                <---- readFrom -----
                                -------------------------------- readFrom ---->

Multiple reads follow this flow:

    I/O System         AsyncCoordinator       AsyncServerEndpoint        AsyncInterpreter
        ===== readReady =====>
                                ----- readInto ---->
                                <---- readFrom -----
                                -------------------------------- readFrom ----->
                                <------------------------------ needsRead -----
                                ----- needsRead --->
                                                      -----+
                                                           | updates I/O key
                                                      <----+
                                <-------------------
        <------ wakeup -------
        ===== readReady =====>

Single write follows this flow:

    I/O System         AsyncCoordinator       AsyncServerEndpoint        AsyncInterpreter
                                <------------------------------- writeFrom ---
                                ----- writeFrom --->

Partial writes follow this flow:

    I/O System         AsyncCoordinator       AsyncServerEndpoint        AsyncInterpreter
                                <------------------------------- writeFrom ---
                                ----- writeFrom --->
                                                      -----+
                                                           | cannot fully write
                                                      <----+
                                <--- needsWrite ----
                                ---- needsWrite --->
                                                      -----+
                                                           | updates I/O key
                                                      <----+
                                <-------------------
         <----- wakeup ------
         ------------------->
                                ------------------->
                                                      -----+
                                                           | put thread in wait
                                                      <----+
          ==== writeReady ===>
                                ~~~~~~~ write ~~~~~>
                                                      ~~~~~+
                                                           | notify thread in wait
                                                      <~~~~+

Buffers are allocated for each connection by the interpreter, for read and for write.

The interpreter is the object that manages concurrency, normally in a way that only one thread at a time can read/write from/to the buffers.
In cases where, for example, the interpreter offers blocking read semantic to user code (like in servlets), one reading thread may be put in wait, another thread may do a further physical read to fill the buffer from where the first reading thread will further read after being notified.

Writes are always blocking, and the endpoint takes care of putting the writing thread in wait in case it cannot physically write to the I/O system, then it register for write interest.
When the I/O system is ready to write, the writing thread is notified and can flush the buffer.