Type Alias openthread_sys::otTcpForwardProgress
source · pub type otTcpForwardProgress = Option<unsafe extern "C" fn(aEndpoint: *mut otTcpEndpoint, aInSendBuffer: usize, aBacklog: usize)>;Expand description
This callback informs the application if forward progress has been made in transferring data from the send buffer to the recipient. This callback is not necessary for correct TCP operation. Most applications can just rely on the otTcpSendDone() callback to reclaim linked buffers once the TCP stack is done using them. The purpose of this callback is to support advanced applications that benefit from finer-grained information about how the the connection is making forward progress in transferring data to the connection peer.
This callback’s operation is closely tied to TCP’s send buffer. The send buffer can be understood as having two regions. First, there is the “in-flight” region at the head (front) of the send buffer. It corresponds to data which has been sent to the recipient, but is not yet acknowledged. Second, there is the “backlog” region, which consists of all data in the send buffer that is not in the “in-flight” region. The “backlog” region corresponds to data that is queued for sending, but has not yet been sent.
The callback is invoked in response to two types of events. First, the “in-flight” region of the send buffer may shrink (e.g., when the recipient acknowledges data that we sent earlier). Second, the “backlog” region of the send buffer may shrink (e.g., new data was sent out). These two conditions often occur at the same time, in response to an ACK segment from the connection peer, which is why they are combined in a single callback.
The TCP stack only uses the @p aInSendBuffer bytes at the tail of the send buffer; when @p aInSendBuffer decreases by an amount x, it means that x additional bytes that were formerly at the head of the send buffer are no longer part of the send buffer and can now be reclaimed (i.e., overwritten) by the application. Note that the otLinkedBuffer structure itself can only be reclaimed once all bytes that it references are no longer part of the send buffer.
This callback subsumes otTcpSendDone(), in the following sense: applications can determine when linked buffers can be reclaimed by comparing @p aInSendBuffer with how many bytes are in each linked buffer. However, we expect otTcpSendDone(), which directly conveys which otLinkedBuffers can be reclaimed, to be much simpler to use. If both callbacks are registered and are triggered by the same event (e.g., the same ACK segment received), then the otTcpSendDone() callback will be triggered first, followed by this callback.
Additionally, this callback provides @p aBacklog, which indicates how many bytes of data in the send buffer are not yet in flight. For applications that only want to add data to the send buffer when there is an assurance that it will be sent out soon, it may be desirable to only send out data when @p aBacklog is suitably small (0 or close to 0). For example, an application may use @p aBacklog so that it can react to queue buildup by dropping or aggregating data to avoid creating a backlog of data.
After a call to otTcpSendByReference() or otTcpSendByExtension() with a positive number of bytes, the otTcpForwardProgress() callback is guaranteed to be called, to indicate when the bytes that were added to the send buffer are sent out. The call to otTcpForwardProgress() may be made immediately after the bytes are added to the send buffer (if some of those bytes are immediately sent out, reducing the backlog), or sometime in the future (once the connection sends out some or all of the data, reducing the backlog). By “immediately,” we mean that the callback is immediately scheduled for execution in a tasklet; to avoid reentrancy-related complexity, the otTcpForwardProgress() callback is never directly called from the otTcpSendByReference() or otTcpSendByExtension() functions.
@param[in] aEndpoint The TCP endpoint for the connection. @param[in] aInSendBuffer The number of bytes in the send buffer (sum of “in-flight” and “backlog” regions). @param[in] aBacklog The number of bytes that are queued for sending but have not yet been sent (the “backlog” region).
Aliased Type§
enum otTcpForwardProgress {
None,
Some(unsafe extern "C" fn(_: *mut otTcpEndpoint, _: usize, _: usize)),
}