= The Message Flow Manager =

This class is an intermediary between the messaging layer (send/receive) and the application code.  It provides the following features:

 * Tracks and reports message flow statistics. 
 * Manages messaging buffers to minimize memory allocations.
 * Optimizes frequency of message sends verses message size. 
 * Optimizes latency vs throughput for request/response (server) style access.

== Discussion ==

This class works by aggregating small messages into larger groups.  Doing so increases latency for small messages in an idle system.  However orders of magnitude performance benefits can be gained by the resulting reduction in process/process and process/kernel context switching, memory allocation, and network bandwidth. In a busy system this efficiency benefit can ultimately reduce average latency for small messages as compared to overwhelming the system with short messages.

This class support simple concatenation of short messages into a single larger packet.  

However, many typical messages have a variable sized internal structure consisting of a header, some variable amount of data, and possibly a trailer.  

This class allows application code to build messages with this structure through multiple, independent calls.


== Header ==
#include <clMsgFlowMgr.hxx>
== APIs ==

{{{#!highlight cpp

namespace SAFplus
  {

  class Message
    {
    public:
    // destination data, only one valid be a union...
    SAFplus::Handle handle;
    Group* grp;
    ClIocAddress addr;

    //? Prefer a more sophisticated scatter/gather technique here, and ability to prepend/append to basic buffer
    char msg[MAX_MSG_SIZE];
    };

  class MessageFlowManager
    {
    public: 

    //? Derived class overrides this to implement the actual send.  The class might use also use this function to "complete" the message if the header needs to be updated WRT number of records or if there is a suffix that needs to be added.
    virtual void send(Message* msg);
    //? Derived class overrides this to implement the message header (if needed) 
    virtual void open(Message* msg);   

    //? Derived class overrides this to report how much data is waiting on the receive queue.  Typically, returning 0 here will trigger all pending send data to be flushed.  0xffffffff means there is no receive queue (this MessageFlowManager instance is not dealing with a server's receive/send data pattern).
    virtual unsigned int recvQueueSize() { return 0xffffffff; }

    //? Send any pending data right now.
    void flush(void);

    // Message Flow Management APIs
    unsigned int maxLatency;  //? Do not wait any longer than this before sending the data
    unsigned int maxSize;     //? If a message exceeds this size, send it right away
    


    // Message construction APIs
   
    //? Get a message buffer with at least maxSize available space
    Message* get(int maxSize);
    //? Queues the message for sending -- may not send right away.  A subsequent call to get() may return this same "msg" for message aggregation.
    void send(Message* msg);  
    };



  }

}}}