Interfaces provided by Pistaches are asynchronous and non-blocking. Asynchronous programming allows for code to continue executing even if the result of a given call is not available yet. Calls that provide an asynchronous interface are referred to asynchronous calls.
An example of such a call is the
send() function provided by the
ResponseWriter interface. This function returns the number of bytes written to the socket file descriptor associated to the connection. However, instead of returning directly the value to the caller and thus blocking the caller, it wraps the value into a component called a
Promise separates the launch of an asynchronous operation from the retrieval of its result. While the asynchronous might still be running, a
Promise<T> is directly returned to the caller to retrieve the final result when it becomes available. A so called continuation can be attach to a
Promise to execute a callback when the result becomes available (when the
Promise has been resolved or fulfilled).
then() member is used to attach a callback to the
Promise. The first argument is a callable that will be called when the
Promise has been succesfully resolved. If, for some reason, an error occurs during the asynchronous operation, a
Promise can be rejected and will then fail. In this case, the second callable will be called.
Async::NoExcept is a special callback that will call
std::terminate() if the promise failed. This is the equivalent of the
Other generic callbacks can also be used in this case:
Async::IgnoreExceptionwill simply ignore the exception and let the program continue
Async::Throwwill "rethrow" the exception up to an eventual promise call-chain. This has the same effect than the
throwkeyword, except that it is suitable for promises
Exceptions in promises callbacks are propagated through an
exception_ptr. Promises can also be chained together to create a whole asynchronous pipeline:
Line 5 will propagate the exception if
fetchDatabase() failed and rejected the promise.