API calls

• int cm_open(struct sockaddr_in *srcaddr, struct sockaddr_in *dstaddr)

cm_open creates (and returns) a new macroflow. It takes as its arguments pointers to the sockaddr_in structures of the source and the destination of the connection (or the stream, aka flow in this document). On error -1 is returned, otherwise 0 is returned.


• int cm_mtu(int id)

Returns the MTU value (in bytes) for a macroflow. It takes the macroflow as its argument.


• int cm_request(int id)

Used by an ALF (Application Level Framing) application to express its desire to send data. Takes macroflow as its argument and returns the status. If the request was scheduled correctly, 0 is returned.  Otherwise -1 is returned. Calling cm_request on an already scheduled flow also returns -1.
 
• int cm_bulk_request(int id, int *list)

An optimization to avoid multiple calls if an application wants to make cm_request() for multiple flows. Takes a macroflow and a list of data sockets (representing individual flows) as its argument. Note that it involves a single system call, rather than the multiple system calls that occur when the application uses cm_request() multiple times.
 
• int cm_update(int id, int nrecd, int nlost, int lossmode, unsigned int rtt)

Used to provide feedback to the CM about the amount of data received or lost for the stream and/or the round-trip time (RTT) value for this flow. Takes a macroflow as its argument. In case of a TCP connection using the CM, the in-kernel TCP uses acknowledgements to do cm_update(). Hence, cm_update() needs to be called only if the user-level application is providing feedback (in particular, for non-TCP-based applications). lossmode can be one of the following: CM_NOLOSS, CM_PERSISTENT, CM_TRANSIENT or CM_ECN. These correspond to no congestion losses, "persistent" losses that cause the stream to lose its TCP-like self-clock, "transient" congestion where the self-clock isn't lost although congestion has occurred, and congestion involving no losses but the use of explicit congestion notification.
 
• int cm_bulk_update(int id, int *list)

An optimization to allow an application to invoke a cm_update() call on multiple streams within a macroflow. Helps reduce the overhead associated with multiple cm_update() calls, especially if the application is managing a large number of streams (e.g., an HTTP server using the CM).
 
• int cm_notify(int id, int nsent)

Used chiefly by IP to notify the CM of the transmission of data. This function should never be called directly from the application, unless nsent = 0 when the application calls it directly.
 
• int cm_bulk_notify(int id, int *list)

An optimization to allow multiple flows to be notified via a single call on the macroflow. Takes a macroflow and a list of data sockets (representing flows) as its argument.
 
• int cm_query(int id, int *ready, cmquery *cmquery)

Used by an application to get statistics for a flow from the CM. Takes a macroflow as its argument and returns the relevant information in the cmquery data structure.
 
• int cm_bulk_query(int id, cmfdquery *cmquery)

An optimization to allow an application to query multiple flows for information. Takes a macroflow as its argument and return the information in cmfdquery data structure.
 
• int cm_getmflow(int id)

Used to get the macroflow corresponding to a stream. Takes the data socket representing the stream as its argument and return macroflow.
 
• int cm_setmflow(int id, int mflow)

Used to assign a stream to a particular macroflow. Takes a data socket descriptor (id) and macroflow (mflow) as its arguments. Returns 0 on success, -1 on error.
 
• int cm_getthresh(int id, cmthresh *cmthresh)

Gets the current value of the threshold parameters for a macroflow (id). These threshold parameters specify when the CM should provide callbacks regarding rate/RTT changes. The threshold parameters are returned in the cmthresh data structure. On success, 0 is returned. On failure, -1 is returned.
 
• int cm_setthresh(int id, cmthresh *cmthresh)

Sets the threshold parameters for a macroflow (id). The threshold parameters to be set must be specified in a cmthresh data structure. On success, 0 is returned. Otherwise, -1 is returned.
 
• int cm_getassoc(int id, int *list)

Returns the set of flows (or data sockets) associated with a particular macroflow (specified in id) in list. On success, the number of flows associated with a macroflow are returned while on failure, -1 is returned.
 
• int cm_setassoc(int id, int *list)

Associates the streams specified in list to a particular macroflow (specified in id). On success,  0 is returned, otherwise -1 is returned.
 
• int cm_close(int id)

Closes and releases the memory associated with a macroflow. Cleans up the state of the macroflow.
 
• int cm_setcongalg(int id, int type)

Used to set the congestion control algorithm for a macroflow. Takes macroflow (id) and the type (type) of congestion control as its argument. type can be either AIMD, representing the traditional TCP style congestion control or BINOMIAL SQRT congestion control, useful for streaming media applications.
 
• void cm_register_send(void (*handler)(int))

Registers the function that will be called by the CM whenever it dispatches on a request callback in response to a cm_request() issued earlier by the application. The function is passed the flow for which transmission has been scheduled as its argument. The registered function gets called when the application unblocks on the macroflow due to request callback and issues cm_dispatch() after that.
 
• void cm_register_update(void(*handler)(int, cmquery))

Registers the function that will be called by the CM whenever it dispatches on a rate callback. The function is passed the flow for which rate callback has happened and the current state of the macroflow in cmquery data structure.  The registered function gets called when the application unblocks on the macroflow due to rate callback and issues cm_dispatch() after that.
 
• void cm_dispatch(int fd, int select_read, int select_write, int select_except)

Used to dispatch an appropriate function based on the type of callback from the CM. The application which is selecting on the macroflow, after unblocking on the macroflow, normally calls cm_dispatch(). cm_dispatch() then, automatically checks the macroflow for either a rate callback or a  request callback and calls the appropriate functions that have been registered for these using cm_register_update() or cm_register_send(). Note that if these functions have not been registered, cm_dispatch() just ignores the relevant callback.

Data structures of the CM API

• cmquery

        typedef struct cmquery {
                    double rate;
                    double srtt;
                    double rttvar;
                    int ratechange;
    } cmquery;

A data structure to hold the results of cm_query(). The current estimate of available rate (or bandwidth in MB/sec) is returned in rate; current smoothed estimate of rtt (in microseconds) is returned in srtt and the variance in rtt is returned in rttvar. The change in rate from the previuos time when cm_query() was done on that macroflow is returned in ratechange.
 

• cmupdate

    typedef struct cmupdate {
                       int nrecd;
                        int nloss;
                        int lossmode;
                        unsigned int rtt;
    } cmupdate;

A data structure used in cm_update() to provide feedback to the CM about the number of bytes successfully received by the receiver (nrecd), the number of bytes lost (nlost), the type of loss (CM_NOLOSS, CM_PERSISTENT, CM_TRANSIENT or CM_ECN) and the most recent rtt estimate (rtt).
 

• cmthresh

        typedef struct cmthresh {
                        float rate_upmult;
                        float rate_downmult;
                        float rtt_upmult;
                        float rtt_downmult;
    } cmthresh;

A data structure used to specify the parameters for notification (callbacks) by the CM on rate changes. rate_upmult specifies the factor increase in available bandwidth for CM to issue callback; rate_downmult specifies the factor by which rate should decrease for the CM to issue a callback; rtt_upmult specifies the factor by which rtt should increase for the CM to issue a callback and similarly, rtt_downmult is the corresponding factor for decrease.
 

• cmfdquery

      typedef struct cmfdquery {
                        int fd;
                        struct cmquery cmquery;
                        int ready;
   } cmfdquery;

A data structure used to return output of cm_bulk_query(). It is an array of cmquery's that is big enough to hold cmquerys of all open cm sockets. The return value is the number of sockets reported on.