I was just reading some Akka docs and I think they aren't very crisp
about the meaning of "blocking" and "async", and I think that might
also confuse some discussions of Future.

For example at one point the docs say "synchronously (blocking) or
asynchronously (non-blocking)" but I would distinguish the two.

Here are two possible definitions:

 * asynchronous: runs without the current stack frame. Because it's
either on another thread's stack, or in this same thread but "later"
(after the current stack frame has been popped), or with the current
stack frame saved as a continuation and then resumed.

 * nonblocking: does not tie up a thread while failing to use CPU. (on
the OS level, does not wait on a descriptor/handle/lock or equivalent;
does not suspend the thread waiting for the OS kernel to re-awaken it)

Another example of confusing this stuff, there was some recent
anti-node.js rant blog post going around that equated "spending time
using CPU" with "blocking" and that distinction in particular is
pretty important in my opinion. If you are blocking on IO/locks, then
tying up a thread is a massive waste of memory resources. If you are
spending time using CPU, then tying up a thread (ideally one thread
out of a pool matching number of CPU cores) is exactly what you want
to do; having an unbounded number of threads using CPU is bad. So the
analysis of node.js was muddled as a result of conflating these
distinct cases.

Anyhow, for explaining something like Future.blocking, I would think
the semantics in these kind of terms have to be made crystal clear; do
I use Future.blocking for long-running CPU-bound computation? For
blocking IO only? etc.