= Async Sessions = == The problem == Traditionally, functions of the Async framework that perform requests (such as async_req()) operate on phones (they are passed a phone ID). In any non-trivial IPC protocol there are operations that consist of more than one IPC call (e.g. VFS_IN_READ) performed either in parallel or in series. (Here we call an operation a set of IPC calls that causes the server to perform a well-defined action). For such protocol it is not possible to perform several operations concurrently on the same phone, because the calls from different operations would get mixed up. For illustration, consider the following client API stub functions: {{{ int my_phone; int mysrv_connect(void) { /* Connect phone to the service */ my_phone = async_connect_me_to(PHONE_NS, SERVICE_MYSRV, 0); } int mysrv_read(int arg, void *buf, size_t bufsize) { /* Send first request R1 (including operation code). */ req = async_send_1(my_phone, MYSRV_READ, arg); /* Send second request (IPC_READ) and wait for result. */ rc = async_data_read_start(my_phone, buf, bufsize); if (rc != EOK) { /* handle error */ } /* Wait for R1 reply. */ async_wait_for(req, &rc); if (rc != EOK) { /* handle error */ } } }}} Were we to call mysrv_read() from two different fibrils A and B concurrently, the server fibril would see some mixture of the sequence (AR1, AR2) with (BR1, BR2), e.g. (AR1, BR1, AR2, BR2) which would be incorrect from the server point of view. Note that the server has no way of telling which request belongs to which operation. We often want to allow such function to be called concurrently in different fibrils. mysrv_read() can block so we cannot serialize calls to it. If we took a character device as an example, we often want to allow one fibril to write while another fibril is blocked in a read operation. == Enter sessions == Session is a ''logical'' datapath from a client to a server which can support ''concurrent'' operations. Each operation is performed in the context of an ''exchange''. An exchange can support an IPC operation (or, ''optionally'', a sequence of operations), but, in any case, only one operation is performed in an exchange at any time. (The ''session''/''connection'' terminology is borrowed from iSCSI and ''exchange'' is borrowed from Fibre Channel transport layer). A client first needs to create a session (to a server) by calling `async_session_create()`. Whenever the client needs to perform an operation, it starts an exchange by calling `async_exchange_begin()` and performs the operation in context of that exchange. Then the client ends the exchange by calling `async_exchange_end()`. We can ammend the example above as follows: {{{ async_sess_t my_session; int mysrv_connect() { int phone; /* Connect phone to the service */ phone = async_connect_me_to(PHONE_NS, SERVICE_MYSRV, 0); /* Create session */ async_session_create(&my_session, phone); } int mysrv_read(int arg, void *buf, size_t bufsize) { int phone; /* Begin exchange */ phone = async_exchange_begin(&my_session); /* Send first request R1 (including operation code). */ req = async_send_1(my_phone, MYSRV_READ, arg); /* Send second request (IPC_READ) and wait for result. */ rc = async_data_read_start(my_phone, buf, bufsize); if (rc != EOK) { /* handle error */ } /* Wait for R1 reply. */ async_wait_for(req, &rc); if (rc != EOK) { /* handle error */ } /* End exchange */ async_exchange_end(&my_session, phone); } }}} Now we can run mysrv_read() in parallel in any number of fibrils/threads. Each IPC request has a context (the exchange) so the different parallel operations will not mix up. Behind the scenes the async framework will do the magic necessary to distinguish the exchanges. In the current implementation it clones the session phone and uses as many separate physical connections as there are concurrent exchanges. It caches the open connections to avoid setting them up and tearing them down too often. In a future implementation the async framework could instead embed an additional qualifier into each IPC request that would allow to distinguish requests from different exchanges (e.g. a virtual path ID).