// -*- C++ -*-
namespace Kite {
//! \typedef SegmentOverlapCostCB
//! Prototype of overlap cost callback functions.
//!
//! \sa TrackSegment::setOverlapCostCB(), TrackSegment::getOverlapCost().
/*! \class TrackElement
*
* \brief Abstract Class for all Elements inserted inside a Track.
*
*
* \section secTrackElementAbstract TrackElement Abstract
*
* The TrackElement class is abstract and is used as base class for
* any element that can be inserted in a Track. It represent the
* footprint of that element inside the Track (an interval).
* Additionnaly it keep a pointer to the Track and it's index inside
* it (Track is implemented with a \c vector<>).
*
* To avoid some explicit dynamic cast later, it provides a default
* implementation for almost all the methods that will be present
* in all the derived classes. All default methods return \c false,
* \c NULL or \c 0 (\e zero) or whatever is appropriated to tell
* it is not meaningful.
*
* <b>Design Note</b>
*
* TrackElement has been designed to serve as a base class for TrackSegment
* and TrackMarker. But, in the end, those two classes have been put in
* separated vectors inside the Track, thus rendering this design choice
* less pertinent. We keep it for now because we may introduce other
* object than TrackSegment inside a Track. If the need do not arise,
* we may merge back TrackElement and TrackSegment.
*/
//! \function bool TrackElement::isFixed() const;
//! \sa Katabatic::AutoSegment::isFixed().
//! \function bool TrackElement::isHorizontal() const;
//! \sa Katabatic::AutoSegment::isHorizontal().
//! \function bool TrackElement::isVertical() const;
//! \sa Katabatic::AutoSegment::isVertical().
//! \function bool TrackElement::isLocal() const;
//! \sa Katabatic::isLocal().
//! \function bool TrackElement::isGlobal() const;
//! \sa Katabatic::AutoSegment::isGlobal().
//! \function bool TrackElement::isBipoint() const;
//! \sa Katabatic::AutoSegment::isBipoint().
//! \function bool TrackElement::isTerminal() const;
//! \sa Katabatic::AutoSegment::isTerminal().
//! \function bool TrackElement::isStrap() const;
//! \sa Katabatic::AutoSegment::isStrap().
//! \function bool TrackElement::isSlackened() const;
//! \sa Katabatic::AutoSegment::isSlackened().
//! \function bool TrackElement::isDogleg() const;
//! \sa Katabatic::isDogleg().
//! \function bool TrackElement::isInvalidated() const;
//! \sreturn \true if the segment is invalidated (may be different from
//! the supporting AutoSegment status).
//! \function bool TrackElement::isCreated() const;
//! \sa Katabatic::AutoSegment::isCreated().
//! \function bool TrackElement::isBlockage() const;
//! \true if the element is a blockage (obstacle).
//! \function bool TrackElement::isLocked() const;
//! \true if the element is part of a net, but must not be
//! moved by the router, whatever the reason.
//! \function bool TrackElement::isRouted() const;
//! \true if the router has placed it.
//! \function bool TrackElement::hasSourceDogleg() const;
//! \red{This method purpose has not been reviewed yet}.
//! \function bool TrackElement::hasTargetDogleg() const;
//! \red{This method purpose has not been reviewed yet}.
//! \function bool TrackElement::canRipple() const;
//! \red{This method purpose has not been reviewed yet}.
//! \function bool TrackElement::canDogleg();
//! \sa AutoSegment::canDogleg(). At Kite level, this variant of the method
//! will apply only on local segments and the segment must not already have
//! a source or target dogleg.
//! \function bool TrackElement::canDogleg( Interval );
//! \sa AutoSegment::canDogleg(). At Kite level, this variant of the method
//! will apply only on local segments and the segment must not already have
//! a source or target dogleg.
//! \function bool TrackElement::canDogleg( Katabatic::GCell* doglegGCell, unsigned int flags );
//! \sa AutoSegment::canDogleg(). At kite level, this variant of the method
//! is mainly targeted to global segment. For local segment it behave like
//! TrackElement::canDogleg(Interval). For global segment, make the break in
//! the requested GCell \c doglegGCell. If it's in the first or last GCell
//! and there is already a dogleg, allow to reuse it if \c flags contains
//! Kite::KtAllowDoglegReuse.
//! \function unsigned long TrackElement::getId() const;
//! \return The \c Id of the supporting AutoSegment, if there is any.
//! \e Zero otherwise.
//! \function unsigned int TrackElement::getDirection() const;
//! \return The direction of the supporting element (should match the
//! preferred direction of the Track).
//! \function Net* TrackElement::getNet() const;
//! \sreturn The Net associated to the element (may be \c NULL).
//! \function const Layer* TrackElement::getLayer() const;
//! \sreturn The Layer of the element (should match the one of the Track).
//! \function Track* TrackElement::getTrack() const;
//! \sreturn The Track into which the element is inserted (may be \c NULL).
//! \function size_t TrackElement::getIndex() const;
//! \sreturn The index of the element inside the Track's vector.
//!
//! \remark If the element is not inserted in a Track, it is set to
//! Track::npos, and obviously must not be used.
//! \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).
//! \function float TrackElement::getMaxUnderDensity ( unsigned int flags=0 ) const;
//! \sreturn The maximum density of all the GCells under this element.
//! \function Box TrackElement::getBoundingBox() const;
//! \sreturn The box that this element uses in the Track.
//! \function TrackElement* TrackElement::getPrevious() const;
//! \sreturn The previous TrackElement, on the same track and of a \e different net.
//! \sa Track::getPrevious().
//! \function TrackElement* TrackElement::getNext() const;
//! \sreturn The next TrackElement, on the same track and of a \e different net.
//! \sa Track::getNext().
//! \function DbU::Unit TrackElement::getAxis() const;
//! \sreturn The axis position of the element (must be the same as the Track).
//! \function DbU::Unit TrackElement::getSourceU() const;
//! \sreturn The minimun of the interval used by the element (cached in an
//! attribute).
//! \function DbU::Unit TrackElement::getTargetU() const;
//! \sreturn The maximum of the interval used by the element (cached in an
//! attribute).
//! \function DbU::Unit TrackElement::getLength() const;
//! \sreturn The length of the interval used by the element.
//! \function Interval TrackElement::getCanonicalInterval() const;
//! \sreturn The interval span used by the element inside the Track.
//! \function Interval TrackElement::getFreeInterval() const;
//! \sreturn The greatest free interval enclosing this element.
//! \function Interval TrackElement::getSourceConstraints() const;
//! \sa Katabatic::AutoSegment::getSourceConstraints().
//! \function Interval TrackElement::getTargetConstraints() const;
//! \sa Katabatic::AutoSegment::getTargetConstraints().
//! \function DataNegociate* TrackElement::getDataNegociate ( unsigned int flags=KtDataSelf ) const;
//! \sreturn The additional data-structure supplied by the routing algorithm.
//! \function TrackElement* TrackElement::getCanonical ( Interval& i );
//! \red{Inner working still unclear to myself.}
//! \function size_t TrackElement::getGCells ( Katabatic::GCellVector& gcells ) const;
//! \sreturn The table of Katabatic::GCell underneath the element whole span.
//! \function unsigned int TrackElement::getDoglegLevel() const;
//! \sreturn The deepness of the dogleg.
//! \function TrackElement* TrackElement::getParent() const;
//! \sreturn The TrackElement from which the dogleg has been created, if any.
//! \function TrackElement* TrackElement::getSourceDogleg ();
//! \sreturn The source part of the segment from which the dogleg has been created.
//! \function TrackElement* TrackElement::getTargetDogleg ();
//! \sreturn The target part of the segment from which the dogleg has been created.
//! \function TrackElements TrackElement::getPerpandiculars ();
//! \sreturn The collection of all element perpandiculars to this one.
//! \function void TrackElement::setFlags ( unsigned int flags );
//! Set to \true \c flags in the element state array.
//! \function void TrackElement::unsetFlags ( unsigned int flags );
//! Reset to \false \c flags in the element state array.
//! \function void TrackElement::setTrack ( Track* track );
//! Insert the element into \c track, also used as an insertion marker.
//! \function void TrackElement::setIndex ( size_t index );
//! Cache the element's index in the Track internal vector.
//! \function void TrackElement::updateFreedomDegree ();
//! Update, from the element characteristics, it's degree of freedom.
//! \function void TrackElement::setDoglegLevel ( unsigned int level );
//! Sets the level of dogleg of the element.
//! \function void TrackElement::swapTrack ( TrackElement* other );
//! Swap the tracks of \c this and \c other.
//! \function void TrackElement::reschedule ( unsigned int level );
//! If the TrackElement has already an event scheduled, change the
//! level of this event, otherwise create a new event.
//!
//! \sa NegotiateWindow::rescheduleEvent().
//! \function void TrackElement::detach ();
//! Remove the link from the TrackElement to it's owning Track, marking
//! it for removal. The removal from the Track's vector is managed by
//! the Track itself during the Session revalidation stage.
//! \function void TrackElement::revalidate ();
//! Actualize the TrackElement characteristics from the supporting
//! elements (set of AutoSegment).
//!
//! \red{Must be completed with the event management}
//! \function void TrackElement::invalidate ();
//! \sa AutoSegment::invalidate().
//! \function void TrackElement::incOverlapCost ( Net* net, TrackCost& cost ) const;
//! \sa Compute the cost of overlap between this segment and the interval
//! specified in \c cost. Mainly calls the relevant callback.
// \function void TrackElement::dataInvalidate ();
// Invalidate the algorithm datas.
// \function void TrackElement::eventInvalidate ();
// Invalidate the associated RoutingEvent (if any).
//! \function void TrackElement::setAxis ( DbU::Unit, unsigned int flags=Katabatic::SegAxisSet );
//! Sets the axis of the TrackElement.
//! \function TrackElement* TrackElement::makeDogleg ();
//! Create a dogleg on the source end of the TrackSegment. Put the dogleg
//! axis on the source \redB{To be further reviewed}.
//!
//! \sa \ref secDogleg "Dogleg management".
//!
//! Post-processing done by TrackSegment::_postDoglegs().
//! \function TrackElement* TrackElement::makeDogleg ( Katabatic::GCell* gcell );
//! \sa AutoSegment::makeDogleg(), \ref secDogleg "Dogleg management".
//!
//! Post-processing done by TrackSegment::_postDoglegs().
//! \function TrackElement* TrackElement::makeDogleg ( Interval interval, unsigned int& flags );
//! \sa AutoSegment::makeDogleg(), \ref secDogleg "Dogleg management", the return flags
//! from this method are returned through the \c flags variable.
//!
//! Post-processing done by TrackSegment::_postDoglegs().
//! \function bool TrackElement::_check () const;
//! Check the coherency of the element. For a TrackSegment:
//! - The supporting AutoSegment the canonical one of the set.
//! - The cached \c min & \c max values are identical to the computed
//! ones.
//!
//! \sreturn \true on success.
//! \function SegmentOverlapCostCB* TrackElement::setOverlapCostCB ( SegmentOverlapCostCB* cb );
//! \param cb the new overlap cost callback.
//! \return the previous overlap cost callback.
//!
//! sets the overlap callback.
/*! \class SegmentObserver
*
* \brief Observer on the base AutoSegment
*
* The observer that will be hooked into the observable in the associated
* canonical AutoSegment. Used to propagate the invalidation/revalidation
* events from AutoSegment toward TrackSegment.
*
* As a secondary function, it is used by the Session::lookup() method
* to quicly retrieve TrackSegment from Katabatic::AutoSegment.
*/
//! \function void SegmentObserver::notify ( unsigned int flags );
//! Implement the asymmetric invalidate/revalidate policy described in
//! Kite::Session. The invalidate is immediatly passed on while the
//! revalidate is ignored.
}