coriolis/kite/doc/TrackSegment.dox

 // -*- C++ -*-


 namespace Kite {

 /*! \class        TrackSegment
  *  \brief        Derived Katabatic::AutoSegment for the router.
  *
  *                \image html  TrackSegment-10.png "Fig 1: TrackSegment Context"
  *
  *                We create one TrackSegment per aligned Katabatic::AutoSegment set,
  *                the TrackSegment is associated to the canonical one of the set.
  *
  *                To provide some speedup, the full extention of the aligned segment
  *                set is computed once and stored in the TrackSegment itself.
  *                The drawback beeing that whenever one segment from the aligned
  *                set has it's extention modified, the full extention must be
  *                recomputed.
  *
  *
  * \section       secTSLazyRevalidate  Lazy Revalidate
  *
  *                When the TrackSegment::revalidate() method is called, it only update
  *                the cached size of the segment (from the AutoSegment set of aligneds)
  *                and the track into which it may be inserted.
  *
  *                The associated DataNegociate and RoutingEvent are \b not updated.
  *                  - The RoutingEvent will be updated when it's key is updated,
  *                    typically during a requeueing operation \b and in the
  *                    SegmentFsm constructor. This should be optimzed in the future.
  *                  - The DataNegociate is updated \e only in the SegmentFsm
  *                    constructor. This is the most costly of the two updates as
  *                    it perform a perpandicular & parallel connexity exploration.
  *
  *
  * \section       secDogleg  Dogleg Management
  *
  *                The basic AutoSegment::canDogleg() method is declined in three more
  *                dedicated methods in this class:
  *                  - TrackSegment::canDogleg(), for locals only, check if a break
  *                    is possible, never break a segment more than once (to avoid
  *                    fragmentation).
  *                  - TrackSegment::canDogleg(Katabatic::GCell*,unsigned int flags)
  *                    for globals, check that the segment is breakable in the desired
  *                    GCell. Never break twice in the first/last GCell (fragmentation
  *                    limitation), but may \e reuse an already existing dogleg.
  *                  - TrackSegment::canDogleg(Interval), for locals only, direct proxy
  *                    for the AutoSegment method. Never allow more than one break.
  *
  *                <b>Relationship between AutoSegment and TrackSegment</b>
  *
  *                Figure 2 below, shows an example of dogleg creation:
  *                  - At the Katabatic level, AutoSegment \c id:12 is broken. Thus
  *                    the creation of AutoSegments \c id:20 and \c id:21. As per
  *                    specification, the orignal segment \c id:10 remains on the
  *                    left side (source) of the break.
  *                  - But, because the canonical of the former aligned AutoSegment
  *                    set \c (10,11,12,13,14) was on the \e right side of the break,
  *                    the new parallel TrackSegment will be created on the \c left
  *                    side, associated to the newly promoted canonical AutoSegment
  *                    \c id:12.
  *
  *                \image html  _makeDogleg-10.png "Fig 2: Dogleg Management"
  *
  *                The TrackSegment::_postDoglegs() method called by all flavors of
  *                TrackSegment::makeDogleg() methods is responsible for creating new
  *                TrackSegments for the new doglegs (there may be more than one), it
  *                also update the dogleg level and source/target dogleg flags.
  *
  *                \redB{This section is not finished.} I need to review the parent and
  *                doglevel numbering management. There seems to be a risk of infinite
  *                fragmentation as the numbering of the original segment is not
  *                increased, we should create a \e break counter separate from
  *                deepness.
  *
  *
  * \section       secWeakGlobal  Global, Weak Global and Local Segments
  *
  *                There's a slight semantic change between Katabatic and Kite about
  *                what is local and what is local. This is due to how we consider the
  *                intermediate status of \e WeakGlobal.
  *
  *                A \c WeakGlobal segment is a local segment which is aligned with a
  *                global (though a VTee or an HTee contact).
  *
  *                In Katabatic a local segment is one that is not \c Global, a local segment
  *                can be both \c Local and \c WeakGlobal.
  *
  *                In Kite a local segment is one that is neither \c Global or \c WeakGlobal.
  *                The \c WeakGlobal sides with \c Global unlike in Katabatic.
  *
  */

 //! \function     static TrackSegment* TrackSegment::create ( AutoSegment* segment, Track* track, bool& created );
 //! \param        segment  The Katabatic AutoSegment to decorate.
 //! \param        track    A Track into which insert the TrackSegment (may be \NULL).
 //! \param        created  This flag is sets is a new TrackSegment has be created.
 //! \return       A TrackSegment wrapped around an AutoSegment.
 //!
 //!               Constructor mainly used at loading time to decorate the Katabatic
 //!               data-base with the router attributes.

 //! \function     unsigned long  TrackElement::getFreedomDegree() const;
 //! \sreturn      The degree of freedom of the element. It is used as a priority value
 //!               when sorting TrackElement (in RoutingEvent).
 //!
 //!               Currently, it is the \e slack of the Katabatic::AutoSegment.

 //! \function    void  TrackSegment::revalidate ();
 //!              Actualize the TrackSegment characteristics from the supporting
 //!              elements (set of AutoSegment).
 //!
 //!              This method do not update the DataNegociate or the RoutingEvent.
 //!              This is a lazy update delayed until the constructor of SegmentFsm is called.
 //!              (see \ref secTSLazyRevalidate "Lazy Revalidate").

 //! \function    TrackSegment* TrackSegment::_postDoglegs ( TrackElement*& perpandicular, TrackElement*& parallel );
 //!              Post-process to be called inside the various dogleg creation or slacken
 //!              methods. Iterate through the newly created AutoSegments to create, for
 //!              the <em>perpandicular</em> and the <em>new parallel</em> associateds
 //!              TrackSegments. Also sets the dogleg levels and flags of the newly
 //!              created elements.
 //!
 //!              The session dogleg reset is called at the end of this method. The \c perpandicular
 //!              and \c parallel references to pointers contains the newly created segments
 //!              for the \b last dogleg. If more than one was created, you cannot access them
 //!              (the need has not arised yet).

 }