Comments on racer behavior.

include/bitcoin/network/async/race_quality.hpp

@@ -29,9 +29,11 @@ namespace libbitcoin {
 namespace network {
 
 /// Not thread safe.
-/// Race is a bind that invokes handler with the first set of arguments
-/// but only after a preconfigured number of invocations. This assists in
-/// synchronizing the results of a set of racing asynchronous operations.
+/// Used in outbound session to invoke for first succeesful handshake.
+/// race_quality invokes complete(args) provided at start(complete), with
+/// args from first successful call to finish(args), with success determined
+/// by first argument in 'args', or upon the last expected invocation of
+/// finish(...), based on the constructor 'size' parameter.
 template <typename... Args>
 class race_quality final
 {

include/bitcoin/network/async/race_speed.hpp

@@ -29,9 +29,10 @@ namespace libbitcoin {
 namespace network {
 
 /// Not thread safe.
-/// Race is a bind that invokes handler with the first set of arguments
-/// but only after a preconfigured number of invocations. This assists in
-/// synchronizing the results of a set of racing asynchronous operations.
+/// Used in connector to race between timer (connection timeout) and connect.
+/// race_speed<Size> invokes complete(args) provided at start(complete), with
+/// args from first call to finish(args), upon the last expected invocation of
+/// finish(...) based on the templatized Size number of expected calls.
 template <size_t Size, typename... Args>
 class race_speed final
 {

include/bitcoin/network/async/race_volume.hpp

@@ -27,9 +27,13 @@ namespace libbitcoin {
 namespace network {
 
 /// Not thread safe.
-/// Race is a bind that invokes handler with the first set of arguments
-/// but only after a preconfigured number of invocations. This assists in
-/// synchronizing the results of a set of racing asynchronous operations.
+/// Used in seed session to continue once sufficient seeding has occurred.
+/// race_volume<Success, Fail>(size, required) invokes sufficient(Success)
+/// provided at start(sufficient, complete) when the first call to finish(count)
+/// is made where count >= required. If no finish is sufficient then the final
+/// call to finish, based on the constructor 'size' parameter, invokes
+/// sufficient(Fail). The final call also invokes complete(Success), regardless
+/// of sufficiency.
 template <error::error_t Success, error::error_t Fail>
 class race_volume final
 {