(ditto)

Author: ygoldfeld

src/flow/async/concurrent_task_loop.hpp

@@ -35,7 +35,7 @@ namespace flow::async
  * ### Thread safety ###
  * All methods are thread-safe for read-write on a shared Concurrent_task_loop, after its ctor returns, unless
  * otherwise specified (but read on).  This is highly significant, just as it is highly significant that boost.asio's
- * `Task_engine::post()` is similarly thread-safe.  However, it is *not* safe to call either stop() or start()
+ * `post(Task_engine&)` is similarly thread-safe.  However, it is *not* safe to call either stop() or start()
  * concurrently with itself or the other of the two, on the same Concurrent_task_loop.
  *
  * ### First, select subclass to instantiate ###
@@ -64,7 +64,7 @@ namespace flow::async
  *   - (This start/stop/run/post paradigm may be familiar to boost.asio (particularly `boost::asio::io_context`) users.)
  *
  * ### Next, post() tasks on it: create_op() to group task into operations ###
- * One can post() a task (in the same way one would simply `Task_engine::post()`).  If one wants to execute an async
+ * One can post() a task (in the same way one would simply `post(Task_engine&)`).  If one wants to execute an async
  * op with 2+ non-concurrent tasks, they would pass the same async::Op to post() for each of the aforementioned 2+
  * `Task`s (which are simply `void` no-arg functions basically).  An async::Op can be created
  * via create_op(); or if the task must be pinned to a specific pre-made per-software-thread async::Op,
@@ -77,7 +77,7 @@ namespace flow::async
  * and that should be enough for most async algorithms.
  *
  * Note also the optional `Synchronicity synchronicity` argument to the `post()` methods.  By default this acts
- * like regular `Task_engine::post()`, but you can also access `Task_engine::dispatch()` type of behavior;
+ * like regular `post(Task_engine&)`, but you can also access `dispatch(Task_engine&)` type of behavior;
  * you can wait for the task to complete using yet another mode.  The latter feature,
  * Synchronicity::S_ASYNC_AND_AWAIT_CONCURRENT_COMPLETION, may be particularly helpful at initialization time, such
  * as if one needs to perform some startup tasks in the new thread(s) before continuing to general work on
@@ -315,7 +315,7 @@ namespace flow::async
  * is considerable flexibility available.  One can think of this as a convenient wrapper around various functionality
  * typically used manually and separately from each other -- simplifying the core interface to just async::Op and
  * post() and providing automatic flexibility as to what functionality is in fact used and when as a result.
- * The functionality accessible: `Task_engine::post()`; scheduling via util::Strand; scheduling on specific thread;
+ * The functionality accessible: `post(Task_engine&)`; scheduling via util::Strand; scheduling on specific thread;
  * non-concurrency guarantees of 2+ tasks in one async op; and thread-count selection and pinning based on available
  * processor architecture (hardware threads, physical cores).
  */
@@ -506,7 +506,7 @@ class Concurrent_task_loop :
    * thread to be idle, but informally -- all else being equal -- that's a great goal.
    *
    * `synchronicity` controls the precise behavior of the "post" operation.  Read #Synchronicity `enum` docs carefully.
-   * That said: if left defaulted, `post()` works in the `Task_engine::post()` manner: return immediately; then
+   * That said: if left defaulted, `post()` works in the `post(Task_engine&)` manner: return immediately; then
    * execute either concurrently in another thread or later in the same thread.
    *
    * This is safe to call after stop(), but `task()` will not run until start() (see stop() doc header).

src/flow/async/segregated_thread_task_loop.hpp

@@ -240,7 +240,7 @@ class Segregated_thread_task_loop :
   // Methods.
 
   /**
-   * Helper performing the core `Task_engine::post()` (or similar) call on behalf of the various `post()` overloads.
+   * Helper performing the core `post(Task_engine&)` (or similar) call on behalf of the various `post()` overloads.
    *
    * @param chosen_task_engine
    *        The value `m_qing_threads[idx].task_engine().` for some valid `idx`: the engine for the thread selected

src/flow/async/single_thread_task_loop.hpp

@@ -35,7 +35,7 @@ namespace flow::async
  * ### Thread safety ###
  * All methods are thread-safe for read-write on a shared Single_thread_task_loop, after its ctor returns, unless
  * otherwise specified (but read on).  This is highly significant, just as it is highly significant that boost.asio's
- * `Task_engine::post()` is similarly thread-safe.  However, it is *not* safe to call either stop() or start()
+ * `post(Task_engine&)` is similarly thread-safe.  However, it is *not* safe to call either stop() or start()
  * concurrently with itself or the other of the two, on the same Single_thread_task_loop.
  *
  * ### Rationale ###
@@ -176,7 +176,7 @@ class Single_thread_task_loop :
    * `Task`.
    *
    * `synchronicity` controls the precise behavior of the "post" operation.  Read #Synchronicity `enum` docs carefully.
-   * That said: if left defaulted, `post()` works in the `Task_engine::post()` manner: return immediately; then
+   * That said: if left defaulted, `post()` works in the `post(Task_engine&)` manner: return immediately; then
    * execute either concurrently in another thread (if called *not* from within another in-thread task) or later in the
    * same thread (otherwise).
    *

src/flow/net_flow/asio/node.hpp

@@ -130,25 +130,25 @@ namespace flow::net_flow::asio
  *   - Asynchronous operations (`asio::*` classes provide these):
  *     - asio::Server_socket::async_accept() -> asio::Peer_socket: Obtain a fully connected peer socket object,
  *       waiting as necessary in background for a connection to come in and fully establish,
- *       then invoking user-provided callback as if by `io_context::post()`.
+ *       then invoking user-provided callback as if by `post(io_context&)`.
  *       - Equivalent: `tcp::acceptor::async_accept()`.
  *       - Variations: optional timeout can be specified.
  *       - Variations: `reactor_pattern` mode, where the `accept()` call itself is left to user handler.
  *     - asio::Node::async_connect() -> net_flow::Peer_socket: Return a fully connected peer socket object,
  *       waiting as necessary in background to reach the remote server and fully establish connection,
- *       then invoking user-provided callback as if by `io_context::post()`.
+ *       then invoking user-provided callback as if by `post(io_context&)`.
  *       - Equivalent: `tcp::socket::async_connect()`.
  *       - Variations: optional timeout can be specified.
  *       - Variations: see also `*_with_metadata()` as above.
  *     - asio::Peer_socket::async_send(): Queue up at least 1 of the N given bytes to send to peer ASAP,
  *       waiting as necessary in background for this to become possible (as explained above),
- *       then invoking user-provided callback as if by `io_context::post()`.
+ *       then invoking user-provided callback as if by `post(io_context&)`.
  *       - Equivalent: `tcp::socket::async_send()`.
  *       - Variations: optional timeout can be specified.
  *       - Variations: `null_buffers` mode, where the `send()` call itself is left to user handler.
  *     - asio::Peer_socket::async_receive(): Dequeue at least 1 of the desired N bytes from peer,
  *       waiting as necessary in background for this to arrive from said remote peer,
- *       then invoking user-provided callback as if by `io_context::post()`.
+ *       then invoking user-provided callback as if by `post(io_context&)`.
  *       - Equivalent: `tcp::socket::async_receive()`.
  *       - Variations: optional timeout can be specified.
  *       - Variations: `null_buffers` mode, where the `receive()` call itself is left to user handler.
@@ -169,7 +169,7 @@ namespace flow::net_flow::asio
  *       - Equivalent: `poll()` with 0 timeout.
  *     - Event_set::async_wait(): Asynchronous I/O multiplixing, like sync_wait() but waits in background and
  *       executes user-provided callback from an unspecified thread.  (A typical callback might set a `future`
- *       result; `io_context::post()` a task to some boost.asio event loop; perhaps set a flag that is
+ *       result; `post(io_context&)` a task to some boost.asio event loop; perhaps set a flag that is
  *       periodically checked by some user thread; or send a byte over some quick IPC mechanism like a POSIX
  *       domain socket or loopback UDP socket -- or even a condition variable.)
  *       - Equivalents: none in POSIX, that I know of.  Windows "overlapped" async I/O sounds vaguely like a distant
@@ -316,7 +316,7 @@ class Node :
    * background, and queueing the user-provided callback on the given boost.asio flow::util::Task_engine.
    * Acts just like connect() but instead of returning a connecting socket immediately, it returns and asycnhronously
    * waits until the initial handshake either succeeds or fails, and then invokes the given callback (in manner
-   * equivalent to boost.asio `Task_engine::post()`), passing to it the connected socket or null, respectively,
+   * equivalent to boost.asio `post(Task_engine&)`), passing to it the connected socket or null, respectively,
    * along with a success #Error_code or otherwise, respectively.  Additionally, you can specify a timeout; not
    * completing the connection by that time is a specific #Error_code.
    *

src/flow/net_flow/asio/peer_socket.hpp

@@ -92,7 +92,7 @@ class Peer_socket :
   /**
    * boost.asio-style asynchronous version that essentially performs non-`null_buffers`
    * net_flow::Peer_socket::sync_receive() in the background and invokes the given handler via the saved
-   * `Task_engine *(async_task_engine())`, as if by `Task_engine::post()`.
+   * `Task_engine *(async_task_engine())`, as if by `post(Task_engine&)`.
    *
    * The semantics are identical to the similar `sync_receive()`, except that the operation does not block the
    * calling thread; and the results are delivered to the supplied handler `on_result` instead of to the caller.
@@ -125,7 +125,7 @@ class Peer_socket :
   /**
    * boost.asio-style asynchronous version that essentially performs a `null_buffers`
    * net_flow::Peer_socket::sync_receive() in the background and invokes the given handler via the saved
-   * `Task_engine *(async_task_engine())`, as if by `Task_engine::post()`.
+   * `Task_engine *(async_task_engine())`, as if by `post(Task_engine&)`.
    *
    * The semantics are identical to the similar `sync_receive()`, except that the operation does not block the
    * calling thread; and the results are delivered to the supplied handler `on_result` instead of to the caller.
@@ -183,7 +183,7 @@ class Peer_socket :
   /**
    * boost.asio-style asynchronous version that essentially performs non-`null_buffers`
    * net_flow::Peer_socket::sync_send() in the background and invokes the given handler via the saved
-   * `Task_engine *(async_task_engine())`, as if by `Task_engine::post()`.
+   * `Task_engine *(async_task_engine())`, as if by `post(Task_engine&)`.
    *
    * The semantics are identical to the similar `sync_send()`, except that the operation does not block the
    * calling thread; and the results are delivered to the supplied handler `on_result` instead of to the caller.
@@ -216,7 +216,7 @@ class Peer_socket :
   /**
    * boost.asio-style asynchronous version that essentially performs a `null_buffers`
    * net_flow::Peer_socket::sync_send() in the background and invokes the given handler via the saved
-   * `Task_engine *(async_task_engine())`, as if by `Task_engine::post()`.
+   * `Task_engine *(async_task_engine())`, as if by `post(Task_engine&)`.
    *
    * The semantics are identical to the similar `sync_send()`, except that the operation does not block the
    * calling thread; and the results are delivered to the supplied handler `on_result` instead of to the caller.

src/flow/net_flow/asio/server_socket.hpp

@@ -107,7 +107,7 @@ class Server_socket :
   /**
    * boost.asio-style asynchronous version that essentially performs
    * net_flow::Server_socket::sync_accept() in the background and invokes the given handler via the saved
-   * `Task_engine *(async_task_engine())`, as if by `Task_engine::post()`.
+   * `Task_engine *(async_task_engine())`, as if by `post(Task_engine&)`.
    *
    * The semantics are identical to the similar `sync_accept()`, except that the operation does not block the
    * calling thread; and the results are delivered to the supplied handler `on_result` instead of to the caller.

src/flow/net_flow/detail/drop_timer.hpp

@@ -171,7 +171,7 @@ class Drop_timer :
   /**
    * Constructs Drop_timer and returns a ref-counted pointer wrapping it.  Saves the "action
    * callbacks" to call when various events fire in this Drop_timer.  The callbacks may be placed
-   * onto `*node_task_engine` in the manner of `Task_engine::post()`, at any future time until done()
+   * onto `*node_task_engine` in the manner of `post(Task_engine&)`, at any future time until done()
    * is called.  At construction, the timer is guaranteed not to fire until the first `on_...()` call.
    *
    * After construction, call `on_...()` as events occur.  If an event described by the doc comment of

src/flow/net_flow/detail/port_space.hpp

@@ -83,7 +83,7 @@ namespace flow::net_flow
  * `boost::filesystem::path`) in `~Port_space()`.  This wouldn't work if Port_space crashed, however.  To
  * solve that, we could easily start a thread in Port_space() (and join it in `~Port_space()`) that
  * would save that state every N seconds.  If that's not enough, we can instead have that thread run
- * a boost.asio `io_context::run()` event loop and `io_context::post()` the save operation onto it (from
+ * a boost.asio `io_context::run()` event loop and `post(io_context&)` the save operation onto it (from
  * arbitrary threads) each time a new ephemeral port is reserved (with some kind of protection
  * against incessant disk writing built into this worker thread; e.g., don't save if saved in the
  * last N msec).

src/flow/net_flow/node.hpp

@@ -2167,7 +2167,7 @@ class Node :
    * Causes an acknowledgment of the given received packet to be included in a future Ack_packet
    * sent to the other side.  That ACK low-level UDP packet is not sent in this handler, even if
    * the low-level UDP socket is currently writable.  The sending of this packet is performed
-   * asynchronously in the manner of `boost::asio::io_context::post()`.
+   * asynchronously in the manner of `boost::asio::post(io_context&)`.
    *
    * Note that the Ack_packet may include other packets being acknowledged; and that ACK may be
    * artificially delayed for reasons like the desire to accumulate more acknowledgments before

src/flow/net_flow/peer_socket.cpp

@@ -326,7 +326,7 @@ Peer_socket_info Peer_socket::info() const
 
   /* There are two cases.  If the socket is open (not S_CLOSED), then an m_node owns it and may
    * change the stats we want to copy in its thread W at any time.  In this case we must copy it in
-   * thread W (which we do using a future and io_context::post(), as in listen() and other places in
+   * thread W (which we do using a future and post(io_context&), as in listen() and other places in
    * Node).  In the socket is closed (S_CLOSED), then no m_node owns it, so there is no thread W
    * applicable to this socket anymore, and we can just copy the data in thread U != W. */