Some quick documentation to async responses

README.md

@@ -8,7 +8,60 @@ Works on several Sinatra and Rails applications. No real testing, yet.
 
 ## Speed
 
-With no optimalizations, refactorings and no JVM tuning the server handles ~ 3000 req/s on my MacBook for simple Rack application.
+With no optimalizations, refactorings and no JVM tuning the server handles ~ 3000 req/s on my MacBook for simple
+Rack application.
+
+## Interfaces
+
+Thick provides interfaces to control it's behaviour.
+
+### Asynchronous responses
+
+Asynchronous responses provide functionality to stream response to the client by chunks.
+
+The most basic API looks
+
+    env['thick.async'].async!(*params, &block)
+
+the application has to respond in a standard manner
+
+    [status, headers, body]
+
+the response will be processed and send to the client, however the connection is not closed, instead the block is
+executed with parameters passed as params. From the block the application can stream data to the client
+
+    env['thick.async'].call(chunk)
+
+after the response is completed the application has to close the connection
+
+    env['thick.async'].close
+
+In more complex scenarios the params and block may be omitted. It's up to the application to wait till the response
+header is sent to the client and stream it's data. To simplify the signalization the application may check if it's safe
+to send it's data by.
+
+    env['thick.async'].ready?
+
+if the method's response is positive it's safe to stream the data.
+
+In the most complex cases it might be necessary to completely bypass default HTTP response generated by the server. In
+those cases the application calls
+
+    env['thick.async'].custom!(*params, &block)
+
+the method informs the server to not send any response on the connection and do not close the connection.
+The contract is the same as with async! mechanism. The block with parameters params is triggered by the server when
+it's safe to stream data. If the block is not given it's completely up to the application to stream the data.
+The application may check whether the server considers safe to stream data by the same way as with async! response
+
+    env['thick.async'].ready?
+
+In the case of custom responses it should be safe to stream right away without checking the server's opinion. Also with
+custom responses it's not necessary to return standard rack response.
+
+## Starting
+
+    thick [-o <interface>] [-p <port>] [-E <environment>]
 
 ## Installation