readme: add a section about waiting for response

The new section covers all available ways of waiting for responses.

Author: drewdzzz

README.md

@@ -182,6 +182,45 @@ request is ready, `wait()` terminates. It also provides negative return code in
 case of system related fails (e.g. broken or time outed connection). If `wait()`
 returns 0, then response is received and expected to be parsed.
 
+### Waiting for Responses
+
+The connector provides several wait methods. All methods accept an integer `timeout`
+argument with the following semantics:
+1. If `timeout > 0`, the connector blocks for `timeout` **milliseconds** or until
+   all required responses are received.
+2. If `timeout == 0`, the connector decodes all available responsed and returns
+   immediately.
+3. If `timeout == -1`, the connector blocks until required responses is received
+   (basically, no timeout).
+
+All the waiting functions (except for `waitAny`, its desctiption will be later)
+return 0 on success, -1 in the case of any internal error or when timeout is exceeded.
+
+Method `wait` waits for one request, optional argument allows to get result right away
+in case of success:
+```c++
+int rc = client.wait(conn, ping, WAIT_TIMEOUT);
+int rc = client.wait(conn, ping, WAIT_TIMEOUT, &result);
+```
+
+Method `waitAll` waits for all requests of a connection from the passed vector:
+```c++
+int rc = client.waitAll(conn, vector_of_futures, WAIT_TIMEOUT);
+```
+
+Method `waitCount` waits until the given connection will receive responses to
+any `future_count` requests:
+```c++
+int rc = client.waitCount(conn, future_count, WAIT_TIMEOUT);
+```
+
+Method `waitAny` is different - it allows to poll all the connections simultaneously.
+In the case of success, the function returns a connection that received a response.
+In the case of internal error or when timeout is exceeded, returns `std::nullopt`.
+```c++
+std::optional<Connection<Buf, NetProvider>> conn_ready = client.waitAny(WAIT_TIMEOUT);
+```
+
 ### Receiving Responses
 
 To get the response when it is ready, we can use `Connection::getResponse()`.