diff --git a/docs/client-design.md b/docs/client-design.md new file mode 100644 index 000000000..cee81fa00 --- /dev/null +++ b/docs/client-design.md @@ -0,0 +1,74 @@ +# Tntcxx Client Design + +## Scope + +This document describes the design of the Client part of Tntcxx. First we +state the requirements and use cases we have in mind, and then we propose a +design that fulfills them. + +## Requirements + +### Functional Requirements + +We envision Tntcxx to be used primarily as a part of network applications (e.g., +an HTTP server), the Client backing requests to Tarantool. Such applications are +usually built around a central event processing loop, which is responsible for +multiplexing network I/O. + +#### Application Event Processing Loop Integration + +The first and foremost requirement is that there must be a convenient +way to integrate the Tntcxx Client into the event processing loop used by the +application. Moreover, the Client must never run the event processing +loop itself. + +At the same time, since event processing loops are inherently single threaded, +we do expect the Tntcxx Client to be used in a multithreaded environment, i.e., +when connections and reqeust futures are in different threads. So we do not aim +to design the Client to be thread-safe. + +#### Asynchronous Request Processing + +Since the Tntcxx Client is constrained from running the event processing loop, +the Client must support asynchronous request processing through +application-provided callbacks. The Client must only be responsible for +posting requests — the responses must be processed and returned to the +application as they arrive, i.e., asynchronously. + +#### Connection Status + +The application must be able to query the status of a Tntcxx Client. + +#### Request Readiness + +The application must be able to query the readiness of a request issued +through the Tntcxx Client. + +#### Request Cancelling + +The application must be able to cancel a request issued through the Tntcxx +Client. + +#### Error Handling + +There must be a convenient exception-safe way for the application to handle +errors arising throughout the Tntcxx Client request lifecycle. + +#### Should the Request Handle give access to the response? + +#### NetworkProvider: Proactor vs Reactor? + +#### Request Retrying? + +#### Transactions? + +#### Connection Pool? + +#### Failover? + +### Non-Functional Requirements + +#### System Call Minimization + +#### Scalability +