// -*- 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 optimized 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. The orignal
* TrackSegment (canonical AutoSegment \c id:10) remains on the
* right side (target) 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).
}