// -*- C++ -*-
namespace Kite {
/*! \class Track
* \brief Structure managing one routing track.
*
* \section secTrackPurpose Track Purpose
*
* We use an array of <em>regularly spaced</em> Track as a geometrical
* fast access structure. It allows to know whether an area is used or
* not. The whole area may be seen as a set of adjoining tiles of fixed
* \e width but variable \e length.
*
* The figure <b>(1.b)</b> show, for an horizontal, track the relation
* between <code>y,min,max</code> and the occupied area of the plane.
* \c min and \c max must take into account segment extensions (\c e) and
* the minimal distance between two rectangles (\c MD) of the same layer.
* We assume that the width of the segment, augmented of all it's
* contraints is no greater than \c TS (in fact it's how \c TS must be
* calculated).
*
* For the whole track array, see RoutingPlane.
*
* \image html Track-0.png "Fig 1: Track Area"
*
*
* \section secTrackImplementation Track Implementation
*
* A Track is implemented with a sorted vector of TrackElement.
* TrackElements from differents nets must not overlap.
* The sorting order is defined as follow:
* - TrackElements are sorted by increasing source (\e min)
* positions.
* - In case of overlap (i.e. belongs to the same net), if
* they share the same source position, then they are sorted
* by \e decreasing length. This way, the longest one will be
* the first encountered when walking through the Track in
* increasing index order.
*
* Figure <b>2.b</b> shows the details of the Track <b>[1]</b> of
* figure <b>1.a</b>. Net \b \<d\> show an exemple of overlapping.
*
* \image html Track-1.png "Fig 2: Track Structure"
* \image latex Track-1.pdf "Track Structure" width=0.7\textwidth
*
* In addition to the TrackSegments, the Track also manage additionnal
* informations through a second vector of TrackMarkers. TrackMarker
* are currently used only to hints at how strongly a terminal is
* dependant on that portion of Track to be accessed.
*
*
* \subsection ssecTrackIndexes Indexes vs. Iterators
*
* Numerical indexes have been prefered over iterators because they can
* be used more easily by objects other the Track itself for referencing.
* So internal managment follow the same rule, handling indexes or
* reference to indexes.
*
*
* \subsection ssecTrackUpdate Update Mechanism
*
* When a TrackElement is normaly inserted in a Track, a two way link
* is established. The Track has an entry in it's vector refering to
* TrackElement, and conversely, the TrackElement has it's \c track
* field pointing to it's owning Track.
*
* <b>TrackElement Removal</b>
*
* To remove a TrackElement from a Track, we break one of those two links:
* the TrackElement cease to refer to the owning Track, marking him for
* removal which will occurs at the next track revalidation (Track::doRemoval()).
* In figure <b>3</b>, the TrackElement belonging to net \b \<b\> is
* marked for removal.
*
* \image html Track-2.png "Fig 3: TrackElement Removal"
*
* <b>TrackElement Insertion</b>
*
* When a TrackElement is inserted into a Track, the two way link is
* immediatly created (but the TrackElement is not yet at it's final
* place in the Track's vector). Before inserting a TrackElement we
* check that it's been already detached (\c track field to \c NULL).
*
* It is at that step that the TrackElement axis is actually updated
* through a call to TrackElement::setAxis().
*
* <b>Revalidation Sequence</b>
*
* After a Track has been modificated either the Track element vector or
* the MarkerElement vector (or both) has been invalidateds. Revalidation
* take place in three steps:
* - Track::doRemoval(), remove all TrackElement marked for removal.
* - Track::insert(), insert the TrackElement into their new Track.
* - Track::doReorder(), sort the TrackElement of the vector, that is, put the
* newly inserted elements at their right place.
*
* Each step must be done <em>for all Tracks</em> before proceeding to the
* next. This way a TrackElement \c track field doesn't get set \e before
* it has been actually removed from it's previous Track.
*
*
*
* \subsection ssecTrackOperations Main Operations on Tracks
*
* <b>Helper Function:</b> Track::getBeginIndex()
*
* Return in \c begin the index of the TrackElement whose minimum is immediately
* below the requested \c position on the Track axis. The second returned
* parameter \c state is a set of flags to tell how the \c begin index
* has to be interpreted.
*
* <b>Helper Function:</b> Track::getOccupiedInterval()
*
* Returns the complete interval of a set of overlapping TrackElement from
* the same net.
*/
//! \enum Track::IndexState
//! Indicates how to compute the bounds of the interval enclosing
//! a given \c position on track axis.
//!
//! \note According to \e position, the interval can be a free interval
//! or a used interval.
//! \var Track::BeginIsTrackMin
//! (implies \c begin=0) there is no TrackElement \e before \c position
//! \var Track::BeginIsSegmentMin
//! The \c begin segment starts \e before \c position and ends \e after.
//! \var Track::BeginIsSegmentMax
//! The \c begin segment starts and ends \e before \c position.
//! \var Track::EndIsTrackMax
//! There is no TrackElement \e after \c position.
//! \var Track::EndIsSegmentMin
//! The \c begin segment starts \e before \c position.
//! \var Track::EndIsNextSegmentMin
//! The \c begin segment starts and ends \e before \c position. So the maximum
//! is given by the \c minimum of the \e next TrackElement.
//! \var Track::EndIsSegmentMax
//! The \c begin segment starts \e before \c position and ends \e after.
//! \var Track::BeforeFirstElement
//! the \c position is before the first TrackElement.
//! \var Track::InsideElement
//! the \c position is inside a TrackElement.
//! \var Track::OutsideElement
//! the \c position is in free zone between two TrackElements.
//! \var Track::AfterLastElement
//! the position is after the end of the last element.
//! \var Track::EmptyTrack
//! the track is still empty.
//! \var Track::BeginMask
//! To extract the \e begin part from a combination of flags.
//! \var Track::EndMask
//! To extract the \e end part from a combination of flags.
//! \var Track::npos;
//! A special index value (greatest integer) meaning that
//! an index is invalid.
//! \function bool Track::isHorizontal () const;
//! \sreturn \true if the Track in horizontal direction.
//! \function bool Track::isVertical () const;
//! \sreturn \true if the Track in vertical direction.
//! \function bool Track::isLocalAssigned () const;
//! \sreturn \true is the Track should be preferentially used for local routing.
//! \function RoutingPlane* Track::getRoutingPlane () const;
//! \sreturn The RoutingPlane owning this Track.
//! \function KiteEngine* Track::getKiteEngine () const;
//! \sreturn The KiteEngine owning this Track.
//! \function unsigned int Track::getDirection () const;
//! \sreturn The direction of the Track, either Katabatic::KbHorizontal or
//! Katabatic::KbVertical.
//! \function RoutingPlane* Track::getIndex () const;
//! \sreturn The index of this Track in the RoutingPlane Track vector.
//! \function unsigned int Track::getDepth () const;
//! \sreturn The depth (as given by the RoutingGauge) of the Track's layer.
//! \function Layer* Track::getLayer () const;
//! \sreturn The \Layer of the Track.
//! \function Layer* Track::getBlockageLayer () const;
//! \sreturn The associated blockage \Layer to the Track's layer.
//! \function DbU::Unit Track::getAxis () const;
//! \sreturn The Axis of the Track.
//! \function DbU::Unit Track::getMin () const;
//! \sreturn The minimal allowed coordinate of the Track.
//! \function DbU::Unit Track::getMax () const;
//! \sreturn The maximal allowed coordinate of the Track.
//! \function Track* Track::getNextTrack () const;
//! \sreturn The next Track in the \RoutingPlane vector. That is the
//! one with the axis immediatly superior.
//! \function Track* Track::getPreviousTrack () const;
//! \sreturn The previous Track in the \RoutingPlane vector. That is the
//! one with the axis immediatly inferior.
//! \function size_t Track::getSize () const;
//! \sreturn The total number of TrackSegment in the Track.
//! \function Point Track::getPosition ( DbU::Unit position ) const;
//! \sreturn the point at \c (position,getAxis()) for horizontal Track
//! at or \c (getAxis(),position) for vertical Track.
//! \function TrackSegment* Track::getSegment ( size_t index ) const;
//! \param index The index of the TrackSegment.
//! \return The TrackSegment at \e index. The result will be \NULL in the
//! follwing cases :
//! - \e index is outside the sorted zone.
//! - \e index points to a hole in the Track.
//! - \e index is equal to Track::npos.
//! \function TrackSegment* Track::getSegment ( DbU::Unit position ) const;
//! \param position The position where to search.
//! \return The TrackSegment whose starting point is immediatly inferior to \e position.
//! \function TrackSegment* Track::getNext ( size_t& index, Net* net ) const;
//! \param index Index of the starting TrackSegment.
//! \param net A \Net to ignore.
//! \return The next TrackSegment (\NULL if not found).
//!
//! Find, starting from TrackSegment at \e index the next TrackSegment
//! ignoring TrackSegment from \e net. \e index is modified to point
//! on the returned TrackSegment. If there's no next TrackSegment (\NULL)
//! then index is set to Track::npos.
//! \function TrackSegment* Track::getPrevious ( size_t& index, Net* net ) const;
//! \param index Index of the starting TrackSegment.
//! \param net A \Net to ignore.
//! \return The previous TrackSegment (\NULL if not found).
//!
//! find, starting from TrackSegment at \e index the previous TrackSegment
//! ignoring TrackSegment from \e net. \e index is modified to point
//! on the returned TrackSegment. If there's no previous TrackSegment (\NULL)
//! then index is set to Track::npos.
//! \function TrackSegment* Track::getNextFixed ( size_t& index ) const;
//! \param index Index of the starting TrackSegment.
//! \return The first previous \e Fixed TrackSegment.
//!
//! find, starting from TrackSegment at \e index the first previous
//! with a \e Fixed attribute set. \e index is modified to point on the
//! returned TrackSegment. If there's no previous TrackSegment (\NULL)
//! then index is set to Track::npos.
//! \function size_t Track::find ( const TrackElement* element ) const;
//! \sreturn the \e index of \e element inside the Track. If the \e element do
//! not belongs to the Track, return Track::npos.
//! \function DbU::Unit Track::getSourcePosition ( size_t index ) const;
//! \sreturn The source position of TrackSegment at index \e index.
//! If \e index is equal to Track::npos, returns zero.
//! \function DbU::Unit Track::getSourcePosition ( vector<TrackElement*>::iterator it ) const;
//! \sreturn The source position of TrackSegment pointed by iterator \e it.
//! If \e it is equal to \c end() , returns zero.
//! \function DbU::Unit Track::getMinimalPosition ( size_t index, unsigned int state ) const;
//! \sreturn Extract the minimal position from the interval at \c index in accordance
//! to \c state hinting.
//!
//! \sa Track::IndexState.
//! \function DbU::Unit Track::getMaximalPosition ( size_t index, unsigned int state ) const;
//! \sreturn Extract the maximal position from the interval at \c index in accordance
//! to \c state hinting.
//!
//! \sa Track::IndexState.
//! \function Interval Track::getFreeInterval ( DbU::Unit position, Net* net=NULL ) const;
//! \param position where fo find a free interval.
//! \param net for which net to find the free interval.
//! \sreturn The longuest free interval enclosing \e position (may be empty).
//! \function Interval Track::getOccupiedInterval ( size_t& begin ) const;
//! \param begin index of one of the TrackElement set. May be modificated.
//! \sreturn the whole interval used by a set of overlaping TrackSegment.
//!
//! As TrackElement from a same net can overlap, the interval of one of
//! them do not give the full extend of the Track occupation at this point.
//! This function looks for all overlaping segments and returns the
//! merged interval. Additionnaly it sets \c begin to the index of the
//! lowest TrackElement of the set.
//!
//! \image html TrackOccupiedInterval-1.png "Fig 4: Track::getOccuppiedInterval()"
//! \function Interval Track::expandFreeInterval ( size_t& begin, size_t& end, unsigned int state, Net* net ) const;
//! \param begin the lowest used TrackSegment.
//! \param end the highest used TrackSegment.
//! \param state tells how to interpret the \c begin & \c end indexes.
//! \param net the for wich we seek place.
//! \sreturn The longuest free interval between \c ]begin,end[ .
//!
//! Starting from the initial <code>[begin,end]</code> interval, expand the
//! interval to encompass all free space or segments belonging to \c net.
//! \c state may be used to compute the interval bounds from \c begin
//! and \c end instead of directly using the returned \c interval.
//!
//! \note \c ]begin,end[ must define a free interval between two TrackSegment.
//! \function void Track::getBeginIndex ( DbU::Unit position, size_t& begin, unsigned int& state ) const;
//! \param position The position where to search.
//! \param begin Index of the immediatly inferior TrackElement.
//! \param state how to interpret the returned \c begin.
//!
//! Return in \c begin the index of the TrackElement whose minimum is immediately
//! below the requested \c position on the Track axis. The second returned
//! parameter \c state is a set of flags to tell how the \c begin index
//! has to be interpreted.
//!
//! Flags for the \c state are:
//! - Track::BeginIsTrackMin : (implies \c begin=0) there is no TrackElement
//! \e before \c position.
//! - Track::EndIsSegmentMin : The \c begin segment starts \e before \c position.
//! - Track::BeginIsSegmentMin : The \c begin segment starts \e before \c position
//! and ends \e after.
//! - Track::EndIsSegmentMax : The \c begin segment starts \e before \c position
//! and ends \e after.
//! - Track::BeginIsSegmentMax : The \c begin segment starts and ends \e before
//! \c position.
//! - Track::EndIsNextSegmentMin : The \c begin segment starts and ends \e before
//! \c position. So the maximum is given by the \c minimum of the \e next
//! TrackElement.
//! - Track::EndIsTrackMax : There is no TrackElement \e after \c position.
//!
//! Based on the previous flags, we build the \c state parameter:
//! - Track::BeforeFirstElement : the \c position is before the first TrackElement.
//! - Track::InsideElement : the \c position is inside a TrackElement.
//! - Track::OutsideElement : the \c position is in free zone between two
//! TrackElements.
//! - Track::AfterLastElement : the position is after the end of the last
//! element.
//! - Track::EmptyTrack : the track is still empty.
//!
//! To separate flags relevant to \e begin and \e end informations, two masks
//! are provideds:
//! - Track::BeginMask
//! - Track::EndMask
//!
//! \image html TrackBeginIndex-1.png "Fig 3: Track::getBeginIndex()"
//!
//! <b>Reminder for myself:</b>
//! The Track::getBeginIndex() function relies on the \STL \lower_bound
//! function. \c lower_bound() finds the TrackElement immediately \e superior
//! to \c position (shown on Figure <b>3</b> by the \c LB label in white on black).
//!
//! The relation between the returned \c begin index and the position is
//! given through the \c state parameter.
//! \function void Track::getOverlapBounds ( Interval interval, size_t& begin, size_t& end ) const;
//! \param interval the overlaping interval.
//! \param begin where to store the starting bound.
//! \param end where to store the ending bound.
//!
//! find the range of TrackSegment intersecting \e interval.
//! Note that when the \e interval lower bound crosses a set of
//! overlaping intervals from the same \Net, the interval at
//! \e begin will crosses the lower bound but some following
//! of the same \Net may not.
//! \function TrackCost Track::getOverlapCost ( Interval interval, Net* net, size_t begin, size_t end, unsigned int flags ) const;
//! \param interval the overlaping interval.
//! \param net a Net to ignore (null cost).
//! \param begin the starting bound.
//! \param end the ending bound.
//! \param flags passed to the overlap cost function.
//! \return The cost of the overlap.
//!
//! Compute the cost of the overlap of \e interval with the range
//! \c [begin,end] of TrackSegment. Any TrackSegment belonging to
//! \e net will be ignored.
//! \function TrackCost Track::getOverlapCost ( Interval interval, Net* net, unsigned int flags ) const;
//! \param interval the overlaping interval.
//! \param net a Net to ignore (null cost).
//! \param flags passed to the overlap cost function.
//!
//! Compute the overlap cost of \e interval with TrackSegment from
//! the current Track, ignoring thoses belonging to \e net.
//! \function TrackCost Track::getOverlapCost ( TrackElement* segment, unsigned int flags ) const;
//! \param segment under which to compute overlap cost.
//! \param flags passed to the overlap cost function.
//!
//! Compute the overlap cost of \c segment with TrackSegment from
//! the current Track (interval and net are deduced from \c segment).
//! \function void Track::getTerminalWeight ( Interval interval, Net* net, size_t& count, unsigned int& weight ) const;
//! \param interval under which to compute terminal weight.
//! \param net a net to be ignored.
//! \param count incremented of the number of track markers under the
//! \c interval.
//! \param weight incremented of the sum of the weight of the track markers
//! under the \c interval.
//!
//! Compute and return the sum of the weight of the track markers (see TrackMarker)
//! under \c interval ignoring \c net (that is, \e for \c net).
//!
//! \remark The referenced variables \c count and \c weight are <b>not</b> reset to
//! zero by this function. It is of the caller's responsability.
//! \function bool Track::check ( unsigned int& overlaps, const char* message=NULL ) const;
//! \param overlaps The number of overlaping segments.
//! \param message An iformative message, only printed if an error occurs.
//! \return \true if the Track contains no incoherencies.
//!
//! Perform a complete Track check. Looks for the following incoherencies :
//! - TrackSegment do not refers this Track.
//! - TrackSegment is detached (TrackSegment::getTrack() is \NULL).
//! - TrackSegment is hollow, this one is very unlikely as hollow
//! TrackSegment are only created for the \lower_bound.
//! - \NULL pointers (should never occurs, nevertheless...)
//! - Two consecutive TrackSegment from different \Net must not
//! overlap.
//! - For TrackSegment starting from the same position, the
//! longuest must be first.
//! \function void Track::invalidate ();
//! Inconditionnaly invalidate the Track, regardless if it has been
//! modificated. The Track will be forced to be revalidated on closure
//! of the current session.
//! \function void Track::insert ( TrackElement* segment );
//! Adds \e segment to the Track. Must only be used inside a
//! Session. They must appears \e after Track::doRemoval()
//! and \e before Track::doReorder().
//!
//! \sa Kite::Session.
//! \function void Track::insert ( TrackMarker* marker );
//! Adds \e marker to the Track. Must only be used inside a
//! Session.
//!
//! \sa Kite::Session.
//! \function void Track::setSegment ( TrackElement* element, size_t index );
//! Directly affect the Track entry at position \c index to
//! \c element (use with great care).
//!
//! \sa Kite::Session.
//! \function size_t Track::doRemoval ();
//! \sreturn The number of removeds TrackSegment.
//!
//! Suppress all the TrackSegment that have been withdraw from the
//! Track. TrackSegment must be withdraw trough the TrackSegment::detach()
//! method which sets their owning Track to \NULL (the removal criterion).
//! It uses the \STL \e remove_if algorithm that put all the to be removed
//! elements at the end of the vector.
//!
//! \sa Kite::Session.
//! \function void Track::doReorder ();
//!
//! (Re)sort the TrackElement of the vector. Must be called \e after:
//! - Track::doRemoval() so no detached TrackSegment are presents.
//! - All calls to Track::insert(), as the newly inserted elements
//! are put at the back of the vector.
//!
//! \sa Kite::Session.
}