1 	    DTN2 Router <-> Convergence Layer Interaction

     2 	    ---------------------------------------------

     3 

     4 

     5 This is an (incomplete) document that describes the contract between

     6 DTN2 routers and convergence layers. XXX/demmer needs more work

     7 

     8 Basic Design

     9 ------------

    10 

    11 Each link has two BundleLists: the queue_ and the inflight_ lists.

    12 A router indicates that it wants to transmit a bundle by calling

    13 BundleActions::queue_bundle. That in turn puts the bundle on the

    14 queue_ and calls ConvergenceLayer::bundle_queued. 

    15 

    16 When the convergence layer initiates transmission of the bundle, it

    17 should call Link::add_to_inflight and Link::del_from_queue on the

    18 bundle. That adjusts the bundle lists to indicate to the rest of the

    19 system that the bundle is actively being transmitted. (May in the

    20 future add an event to indicate this).

    21 

    22 Once the bundle transmission has completed, the convergence layer

    23 should post a BundleTransmittedEvent to indicate it. 

    24 

    25 Backpressure

    26 ------------

    27 

    28 Each link queue has a configurable queue depth with a high water and

    29 low water mark. That limits the number of bundles that will be queued

    30 on the link and provides backpressure to the rest of the system. 

    31 

    32 The router responds to bundle transmitted events by checking whether

    33 the link queue has space for new bundles, and if so will initiate new

    34 transmissions by queuing more bundles there

    35 

    36 Link Closures

    37 -------------

    38 

    39 When links close, any bundles that are currently inflight (i.e. on the

    40 inflight list) should be put back onto the link queue by the

    41 convergence layer. Then when the link is re-opened, the convergence

    42 layer should initiate transmission of the bundles that are on the

    43 queue, as it will not get additional bundles_queued() calls when the

    44 link reopens.

    45 

    46 Cancelling Bundles

    47 ------------------

    48 

    49 If routers have queued bundles on a link and want to cancel

    50 transmission, they should call BundleActions::cancel_bundle. If the

    51 bundle is on the link queue, it is simply removed from the queue,

    52 no indication is given to the convergence layer, and a

    53 BundleSendCancelledEvent is posted. If the bundle is on the inflight

    54 queue, then ConvergenceLayer::cancel_bundle is called. If the

    55 convergence layer can cancel transmission, it should. If not, it can

    56 ignore the call and then presumably eventually complete transmission.