An imperative client API.
Synchronous waiting (blocking) in languages with futures but not coroutines
The endpoint lifecycle methods connect, open-session,
open-sender, and open-receiver start their respective operations
but do not complete them.
Under normal circumstances, you won't need to wait for these to
complete because subsequent operations will internally wait as needed.
If you do need to wait explicitly, you can use the endpoint wait
method to block until the connect or open operation completes.
All endpoints have a close method that returns a waitable future
resolving to the endpoint object itself.
The sender send method blocks until there is credit for sending.
It then sends the message and returns a tracker object. Use the
tracker wait method to block until delivery at the remote peer is
acknowledged. try-send is a variant that returns null instead of
blocking if there is no credit.
The receiver receive method blocks until a delivery is available
to return. try-receive is a variant that instead returns null
if no deliveries have been received.
Blocking operations take optional timeout arguments. If the timeout is exceeded, they raise a timeout error.
Asynchronous waiting in languages with coroutines
As described above, a language without coroutines has blocking of
two kinds: first, the blocking the library performs inside some API
calls, and second, the blocking the API user performs when using
wait methods or futures offered by the API. For example, send
blocks internally for credit and then exposes a wait method which
the API user can use to block until delivery is confirmed.
For languages that do support coroutines, this somewhat tactical division is not desirable. Here we outline the differences we would expect to see in a rendering of this API in a language with coroutines.
In general, any operation that blocks or returns a future instead
returns an awaitable task. This applies to the endpoint wait
and close operations.
The sender send method does not block the API thread for credit.
Instead, it returns an awaitable task that itself waits
asynchronously for both credit and confirmation of delivery. There
is no try-send variant.
The receiver receive method does not block the API thread until
a delivery arrives. Instead, it returns an awaitable task that gets
the next delivery. There is no try-receive variant.
Alternative method definitions for languages with coroutines are
prefixed with (async) in the API reference. In an implementation,
the prefixes would be omitted.
| Class | Summary |
|---|---|
| client | A top-level container of connections, sessions, senders, and receivers |
| client-options | Options for new clients |
| connection | A channel for communication between two peers on a network |
| session | A container of senders and receivers |
| sender | A channel for sending messages |
| receiver | A channel for receiving messages |
| tracker | A tracker for a sent message |
| delivery | A received message |