billf / asio-utilities

helper functions to make working with async easier

ASIO Utilities

Obsolete In HHVM 3.11+

These functions have been merged into HHVM, and we expected them to be included from 3.11.0 onwards.

Installation

• add hhvm/asio-utilities to your composer.json

ResultOrExceptionWrapper

When awaiting multiple handles, it can be useful to isolate exceptions from each; ResultOrExceptionWrapper provides this:

// HH\Asio\wrap(T): Awaitable<ResultOrExceptionWrapper<T>>
$w = await wrap(some_async_function_that_may_throw());
if ($w->isSucceeded()) {
  $result = $w->getResult();
  ...
} else {
  $exception = $w->getException();
  ...
}

Mapping and Filtering Functions

HHVM 3.6 and above include HH\Asio\v() and HH\Asio\m() to make it easy to wait on multiple wait handles; it's fairly common to want to combine this with another option, such as mapping or filtering with an async function.

These functions are named according to their attributes:

First, how they take and return arguments according to types:

• v - Vector
• m - Map

Then, either one or two letters to indicate the operation:

• f - filter
• fk - filter with key
• m - map
• mk - map with keys

Finally, there is optionally a trailing 'w' to indicate that you want a result or exception wrapper. For 'fw' functions, the behavior is that:

• if the filter function returns true, the wrapped element is returned
• if the filter function returns false, the element is omitted
• if the filter function throws an exception, the wrapped exception is returned

This is also available without a filter or mapping operation - vw() and mw().

Function List

All functions are in the HH\Asio namespace; v() and m() are built in to HHVM 3.6 and newer.

Name	Returns	Mapped	Filtered	with key	Wrapped	Callback
v()	Vector<T>	❌	❌	❌	❌
vm()	Vector<Tr>	✅	❌	❌	❌	(Tv): Awaitable<Tr>
vmk()	Vector<Tr>	✅	❌	✅	❌	(Tk, Tv): Awaitable<Tr>
vf()	Vector<Tv>	❌	✅	❌	❌	(Tv): Awaitable<bool>
vfk()	Vector<Tv>	❌	✅	✅	❌	(Tk, Tv): Awaitable<bool>
vw()	Vector<ResultOrExceptionWrapper<T>>	❌	❌	❌	✅
vmw()	Vector<ResultOrExceptionWrapper<Tr>>	✅	❌	❌	✅	(Tv): Awaitable<Tr>
vmkw()	Vector<ResultOrExceptionWrapper<Tr>>	✅	❌	✅	✅	(Tk, Tv): Awaitable<Tr>
vfw()	Vector<ResultOrExceptionWrapper<Tv>>	❌	✅	❌	✅	(Tv): Awaitable<bool>
vfkw()	Vector<ResultOrExceptionWrapper<Tv>>	❌	✅	✅	✅	(Tk, Tv): Awaitable<bool>
m()	Map<Tk, Tv>	❌	❌	❌	❌
mm()	Map<Tk, Tr>	✅	❌	❌	❌	(Tv): Awaitable<Tr>
mmk()	Map<Tk, Tr>	✅	❌	✅	❌	(Tk, Tv): Awaitable<Tr>
mf()	Map<Tk, Tv>	❌	✅	❌	❌	(Tv): Awaitable<bool>
mfk()	Map<Tk, Tv>	❌	✅	✅	❌	(Tk, Tv): Awaitable<bool>
mw()	Map<Tk, ResultOrExceptionWrapper<T>>	❌	❌	❌	✅
mmw()	Map<Tk, ResultOrExceptionWrapper<Tr>>	✅	❌	❌	✅	(Tv): Awaitable<Tr>
mmkw()	Map<Tk, ResultOrExceptionWrapper<Tr>>	✅	❌	✅	✅	(Tk, Tv): Awaitable<Tr>
mfw()	Map<Tk, ResultOrExceptionWrapper<Tv>>	❌	✅	❌	✅	(Tv): Awaitable<bool>
mfkw()	Map<Tk, ResultOrExceptionWrapper<Tv>>	❌	✅	✅	✅	(Tk, Tv): Awaitable<bool>