rfc3124.txt

RFC 的详细文档！

                                      Figure 1

   The key components of the CM framework are (i) the API, (ii) the
   congestion controller, and (iii) the scheduler.  The API is (in part)
   motivated by the requirements of application-level framing (ALF)
   [Clark90], and is described in Section 4.  The CM internals (Section
   5) include a congestion controller (Section 5.1) and a scheduler to
   orchestrate data transmissions between concurrent streams in a
   macroflow (Section 5.2).  The congestion controller adjusts the
   aggregate transmission rate between sender and receiver based on its
   estimate of congestion in the network.  It obtains feedback about its
   past transmissions from applications themselves via the API.  The
   scheduler apportions available bandwidth amongst the different
   streams within each macroflow and notifies applications when they are
   permitted to send data.  This document focuses on well-behaved
   applications; a future one will describe the sender-receiver protocol
   and header formats that will handle applications that do not
   incorporate their own feedback to the CM.

3. CM API

   By convention, the IETF does not treat Application Programming
   Interfaces as standards track.  However, it is considered important
   to have the CM API and CM algorithm requirements in one coherent
   document.  The following section on the CM API uses the terms MUST,



Balakrishnan, et. al.       Standards Track                     [Page 6]

RFC 3124                 The Congestion Manager                June 2001


   SHOULD, etc., but the terms are meant to apply within the context of
   an implementation of the CM API.  The section does not apply to
   congestion control implementations in general, only to those
   implementations offering the CM API.

   Using the CM API, streams can determine their share of the available
   bandwidth, request and have their data transmissions scheduled,
   inform the CM about successful transmissions, and be informed when
   the CM's estimate of path bandwidth changes.  Thus, the CM frees
   applications from having to maintain information about the state of
   congestion and available bandwidth along any path.

   The function prototypes below follow standard C language convention.
   We emphasize that these API functions are abstract calls and
   conformant CM implementations may differ in specific details, as long
   as equivalent functionality is provided.

   When a new stream is created by an application, it passes some
   information to the CM via the cm_open(stream_info) API call.
   Currently, stream_info consists of the following information: (i) the
   source IP address, (ii) the source port, (iii) the destination IP
   address, (iv) the destination port, and (v) the IP protocol number.

3.1 State maintenance

   1. Open: All applications MUST call cm_open(stream_info) before
      using the CM API.  This returns a handle, cm_streamid, for the
      application to use for all further CM API invocations for that
      stream.  If the returned cm_streamid is -1, then the cm_open()
      failed and that stream cannot use the CM.

      All other calls to the CM for a stream use the cm_streamid
      returned from the cm_open() call.

   2. Close: When a stream terminates, the application SHOULD invoke
      cm_close(cm_streamid) to inform the CM about the termination
      of the stream.

   3. Packet size: cm_mtu(cm_streamid) returns the estimated PMTU of
      the path between sender and receiver.  Internally, this
      information SHOULD be obtained via path MTU discovery
      [Mogul90].  It MAY be statically configured in the absence of
      such a mechanism.








Balakrishnan, et. al.       Standards Track                     [Page 7]

RFC 3124                 The Congestion Manager                June 2001


3.2 Data transmission

   The CM accommodates two types of adaptive senders, enabling
   applications to dynamically adapt their content based on prevailing
   network conditions, and supporting ALF-based applications.

   1. Callback-based transmission.  The callback-based transmission API
   puts the stream in firm control of deciding what to transmit at each
   point in time.  To achieve this, the CM does not buffer any data;
   instead, it allows streams the opportunity to adapt to unexpected
   network changes at the last possible instant.  Thus, this enables
   streams to "pull out" and repacketize data upon learning about any
   rate change, which is hard to do once the data has been buffered.
   The CM must implement a cm_request(i32 cm_streamid) call for streams
   wishing to send data in this style.  After some time, depending on
   the rate, the CM MUST invoke a callback using cmapp_send(), which is
   a grant for the stream to send up to PMTU bytes.  The callback-style
   API is the recommended choice for ALF-based streams.  Note that
   cm_request() does not take the number of bytes or MTU-sized units as
   an argument; each call to cm_request() is an implicit request for
   sending up to PMTU bytes.  The CM MAY provide an alternate interface,
   cm_request(int k).  The cmapp_send callback for this request is
   granted the right to send up to k PMTU sized segments.  Section 4.3
   discusses the time duration for which the transmission grant is
   valid, while Section 5.2 describes how these requests are scheduled
   and callbacks made.

   2. Synchronous-style.  The above callback-based API accommodates a
   class of ALF streams that are "asynchronous."  Asynchronous
   transmitters do not transmit based on a periodic clock, but do so
   triggered by asynchronous events like file reads or captured frames.
   On the other hand, there are many streams that are "synchronous"
   transmitters, which transmit periodically based on their own internal
   timers (e.g., an audio senders that sends at a constant sampling
   rate).  While CM callbacks could be configured to periodically
   interrupt such transmitters, the transmit loop of such applications
   is less affected if they retain their original timer-based loop.  In
   addition, it complicates the CM API to have a stream express the
   periodicity and granularity of its callbacks.  Thus, the CM MUST
   export an API that allows such streams to be informed of changes in
   rates using the cmapp_update(u64 newrate, u32 srtt, u32 rttdev)
   callback function, where newrate is the new rate in bits per second
   for this stream, srtt is the current smoothed round trip time
   estimate in microseconds, and rttdev is the smoothed linear deviation
   in the round-trip time estimate calculated using the same algorithm
   as in TCP [Paxson00].  The newrate value reports an instantaneous
   rate calculated, for example, by taking the ratio of cwnd and srtt,
   and dividing by the fraction of that ratio allocated to the stream.



Balakrishnan, et. al.       Standards Track                     [Page 8]

RFC 3124                 The Congestion Manager                June 2001


   In response, the stream MUST adapt its packet size or change its
   timer interval to conform to (i.e., not exceed) the allowed rate.  Of
   course, it may choose not to use all of this rate.  Note that the CM
   is not on the data path of the actual transmission.

   To avoid unnecessary cmapp_update() callbacks that the application
   will only ignore, the CM MUST provide a cm_thresh(float
   rate_downthresh, float rate_upthresh, float rtt_downthresh, float
   rtt_upthresh) function that a stream can use at any stage in its
   execution.  In response, the CM SHOULD invoke the callback only when
   the rate decreases to less than (rate_downthresh * lastrate) or
   increases to more than (rate_upthresh * lastrate), where lastrate is
   the rate last notified to the stream, or when the round-trip time
   changes correspondingly by the requisite thresholds.  This
   information is used as a hint by the CM, in the sense the
   cmapp_update() can be called even if these conditions are not met.

   The CM MUST implement a cm_query(i32 cm_streamid, u64* rate, u32*
   srtt, u32* rttdev) to allow an application to query the current CM
   state.  This sets the rate variable to the current rate estimate in
   bits per second, the srtt variable to the current smoothed round-trip
   time estimate in microseconds, and rttdev to the mean linear
   deviation.  If the CM does not have valid estimates for the
   macroflow, it fills in negative values for the rate, srtt, and
   rttdev.

   Note that a stream can use more than one of the above transmission
   APIs at the same time.  In particular, the knowledge of sustainable
   rate is useful for asynchronous streams as well as synchronous ones;
   e.g., an asynchronous Web server disseminating images using TCP may
   use cmapp_send() to schedule its transmissions and cmapp_update() to
   decide whether to send a low-resolution or high-resolution image.  A
   TCP implementation using the CM is described in Section 6.1.1, where
   the benefit of the cm_request() callback API for TCP will become
   apparent.

   The reader will notice that the basic CM API does not provide an
   interface for buffered congestion-controlled transmissions.  This is
   intentional, since this transmission mode can be implemented using
   the callback-based primitive.  Section 6.1.2 describes how
   congestion-controlled UDP sockets may be implemented using the CM
   API.

3.3 Application notification

   When a stream receives feedback from receivers, it MUST use
   cm_update(i32 cm_streamid, u32 nrecd, u32 nlost, u8 lossmode, i32
   rtt) to inform the CM about events such as congestion losses,



Balakrishnan, et. al.       Standards Track                     [Page 9]

RFC 3124                 The Congestion Manager                June 2001


   successful receptions, type of loss (timeout event, Explicit
   Congestion Notification [Ramakrishnan99], etc.) and round-trip time
   samples.  The nrecd parameter indicates how many bytes were
   successfully received by the receiver since the last cm_update call,
   while the nrecd parameter identifies how many bytes were received
   were lost during the same time period.  The rtt value indicates the
   round-trip time measured during the transmission of these bytes.  The
   rtt value must be set to -1 if no valid round-trip sample was
   obtained by the application.  The lossmode parameter provides an
   indicator of how a loss was detected.  A value of CM_NO_FEEDBACK
   indicates that the application has received no feedback for all its
   outstanding data, and is reporting this to the CM.  For example, a
   TCP that has experienced a timeout would use this parameter to inform
   the CM of this.  A value of CM_LOSS_FEEDBACK indicates that the
   application has experienced some loss, which it believes to be due to
   congestion, but not all outstanding data has been lost.  For example,
   a TCP segment loss detected using duplicate (selective)
   acknowledgments or other data-driven techniques fits this category.
   A value of CM_EXPLICIT_CONGESTION indicates that the receiver echoed
   an explicit congestion notification message.  Finally, a value of
   CM_NO_CONGESTION indicates that no congestion-related loss has
   occurred.  The lossmode parameter MUST be reported as a bit-vector
   where the bits correspond to CM_NO_FEEDBACK, CM_LOSS_FEEDBACK,
   CM_EXPLICIT_CONGESTION, and CM_NO_CONGESTION.  Note that over links
   (paths) that experience losses for reasons other than congestion, an
   application SHOULD inform the CM of losses, with the CM_NO_CONGESTION
   field set.

   cm_notify(i32 cm_streamid, u32 nsent) MUST be called when data is
   transmitted from the host (e.g., in the IP output routine) to inform
   the CM that nsent bytes were just transmitted on a given stream.
   This allows the CM to update its estimate of the number of
   outstanding bytes for the macroflow and for the stream.

   A cmapp_send() grant from the CM to an application is valid only for
   an expiration time, equal to the larger of the round-trip time and an
   implementation-dependent threshold communicated as an argument to the
   cmapp_send() callback function.  The application MUST NOT send data
   based on this callback after this time has expired.  Furthermore, if
   the application decides not to send data after receiving this
   callback, it SHOULD call cm_notify(stream_info, 0) to allow the CM to
   permit other streams in the macroflow to transmit data.  The CM
   congestion controller MUST be robust to applications forgetting to
   invoke cm_notify(stream_info, 0) correctly, or applications that
   crash or disappear after having made a cm_request() call.






Balakrishnan, et. al.       Standards Track                    [Page 10]

RFC 3124                 The Congestion Manager                June 2001


3.4 Querying

   If applications wish to learn about per-stream available bandwidth
   and round-trip time, they can use the CM's cm_query(i32 cm_streamid,
   i64* rate, i32* srtt, i32* rttdev) call, which fills in the desired
   quantities.  If the CM does not have valid estimates for the
   macroflow, it fills in negative values for the rate, srtt, and
   rttdev.

3.5 Sharing granularity

   One of the decisions the CM needs to make is the granularity at which
   a macroflow is constructed, by deciding which streams belong to the
   same macroflow and share congestion information.  The API provides
   two functions that allow applications to decide which of their
   streams ought to belong to the same macroflow.

   cm_getmacroflow(i32 cm_streamid) returns a unique i32 macroflow
   identifier.  cm_setmacroflow(i32 cm_macroflowid, i32 cm_streamid)
   sets the macroflow of the stream cm_streamid to cm_macroflowid.  If
   the cm_macroflowid that is passed to cm_setmacroflow() is -1, then a
   new macroflow is constructed and this is returned to the caller.
   Each call to cm_setmacroflow() overrides the previous macroflow
   association for the stream, should one exist.

   The default suggested aggregation method is to aggregate by
   destination IP address; i.e., all streams to the same destination
   address are aggregated to a single macroflow by default.  The
   cm_getmacroflow() and cm_setmacroflow() calls can then be used to
   change this as needed.  We do note that there are some cases where
   this may not be optimal, even over best-effort networks.  For
   example, when a group of receivers are behind a NAT device, the
   sender will see them all as one address.  If the hosts behind the NAT
   are in fact connected over different bottleneck links, some of those
   hosts could see worse performance than before.  It is possible to
   detect such hosts when using delay and loss estimates, although the
   specific mechanisms for doing so are beyond the scope of this
   document.

   The objective of this interface is to set up sharing of groups not
   sharing policy of relative weights of streams in a macroflow.  The
   latter requires the scheduler to provide an interface to set sharing
   policy.  However, because we want to support many different
   schedulers (each of which may need different information to set
   policy), we do not specify a complete API to the scheduler (but see






Balakrishnan, et. al.       Standards Track                    [Page 11]