A Re-design of Channel APIs

[ddmbr]

Overview

The Channels should have a hierarchy of APIs, with the two most high-level methods in() and out().

in --+-- recv
     |
     +-- post_recv

out -+-- pre_send
     |
     +-- send
     |
     +-- post_send

Details

Second-level primitives

Here's the rationale of the second-level primitives. recv() is for polling mailbox and parsing the incoming messages. post_recv() is for various synchronization and declaring the completion of the receiving process.

pre_send() facilitates aggregation. For example we may want to combine the messages before sending them to network. send() will mainly use LocalMailbox::send(). post_send() declares completion of the sending process (e.g., by using LocalMailbox::send_complete()) and possibly clears the buffers for incoming messages.

Third-level primitives

There is another hierarchy inside recv(), illustrated as follows,

recv -- process_bin_stream -- [recv_callback]

After recv() gets one BinStream, it gets processed by process_bin_stream(). Inside process_bin_stream(), it extracts many messages from one BinStream, and for each message, it invokes the recv_callback() .

One important point here is that, while all other methods are presented in the ChannelBase, the recv_callback() is optional, and it's application-specific. In another word, it may have different signatures in different types of channels. It should be implemented as a std::function so that it can be replaced during runtime.

According modification in other components

In order to simplify things, channels should no longer get registered in ObjList. list_exec should always take four arguments.