This function has been used for testing tor-netdir, but it will also
be useful for testing path selection in tor-cirmgr as well.
I've put it behind a "testing" feature, since it shouldn't really be
used by most applications.
As with the tor-chanmgr code, the circuit manager is now implemented
using an AbstractCircMgr type that uses traits to abstract the
particular behavior of other types that it uses. (Specifically:
circuits, building circuits, and telling whether one circuit usage
is compatible with another.) Abstracting out the dependencies in
this ways makes it possible to test the circuit manager without
having to actually build real circuits.
This commit also introduces new behavior for handling pending
circuit requests. Upon getting a new request, first we check to see
if there's an existing circuit we can use. If there isn't, we look
for pending circuits and wait for them. If there aren't any pending
circuits we can use, we launch one or more, and wait for them.
So far, that's the same as the old behavior. But here's a change:
if, while we are waiting for some pending circuits, a different
circuit is completed, and it's one we could use, then the task that
was building _that_ circuit will tell us: "please look at this
circuit". This gives us better changes of getting a usable circuit
fast.
Minor changes:
* The Error type in CircMgr no longer uses anyhow; several errors
have been simplified.
* We've gotten more formal about the relationship between circuit
usage and target usage.
To make this work we have to wrap std::io::Error in an Arc. The
benefit of having these errors implement Clone is that we can
provide the same Error in response to multiple requests when they
are all waiting on the same operation.
The previous API required the caller to check that the meta-cell it
got was coming from the right hop; the new API requires the caller
to say which hop it expects to get a cell from. With this change,
it's not possible to omit the correct-hop check.