// -*- C++ -*-
namespace Kite {
/*! \class Manipulator
* \brief Handle TrackElement ripup & topological modifications.
*
* \section secManipStruct Manipulator Structure
*
* A Manipulator basically binds together a TrackElement, it's
* DataNegociate and RoutingEvent (cached for fast access), and
* \b a SegmentFsm.
*
* <em>The TrackElement may differs from the one of the SegmentFsm.</em>
* This can occurs when manipulating perpandiculars or segments from
* other nets in conflict. For example: Manipulator::isCaged().
*
* In the following documentation, the segment <em>which is associated
* to the SegmentFsm</em> will be called the <em>reference segment</em>.
*
* \section secManipDelayed Delayed Modifications
*
* It is important to note that when a Manipulator is called to
* modificate a TrackElement, nothing is actually done by the
* Manipulator itself. Instead, the Manipulator create the
* relevant SegmentAction (s) that are stored in the SegmentFsm.
* The action themselves are done at the end of the SegmentFsm
* lifecycle (wrapped inside a Session).
*
* \red{This is not true!} When dogleg are created, the topology is
* immediatly modificated. That way of doing must be clarified.
*/
//! \enum Manipulator::FunctionFlag
//! The various flags that can be passed to the Manipulator methods.
//! \var Manipulator::ToRipupLimit
//! The ripup limit must be immediatly to it's limit for the current
//! state.
//! \var Manipulator::AllowExpand
//! Allow break points for dogleg not to be exactly on the requested
//! position. Meaning that they are moved to the least congested
//! GCell.
//! \var Manipulator::NoExpand
//! Breakpoints for dogleg are kept right where they are requested.
//! \var Manipulator::PerpandicularsFirst
//! Reorder the events so that perpandiculars segments are re-processed
//! before their reference segment. By default this is the other way
//! around.
//! \var Manipulator::ToMoveUp
//! Try to move up ripped up segments.
//! \var Manipulator::AllowLocalMoveUp
//! Allow local segments to be moved up (forbidden by default).
//! \var Manipulator::AllowTerminalMoveUp
//! Allow terminal segments to be moved up (forbidden by default).
//! \var Manipulator::AllowShortPivotUp
//! Allow short segment yo be pivoted up.
//! \var Manipulator::NoDoglegReuse
//! When creating a dogleg, the default behavior is \e not to create a
//! new one if there's already one in the same GCell. If this flag is
//! set, a second dogleg will be created.
//! \var Manipulator::RightAxisHint
//! An explicit right axis hint has been supplied as argument.
//! \var Manipulator::LeftAxisHint
//! An explicit left axis hint has been supplied as argument.
//! \var Manipulator::NotOnLastRipup
//! The reference segment has still more than one ripup to go for
//! the given state.
//! \function Manipulator::Manipulator ( TrackElement* segment, SegmentFsm& fsm );
//! \param segment The TrackElement to manipulate.
//! \param fsm The associated SegmentFsm.
//!
//! Construct a new Manipulator on \c segment.
//! \function TrackElement* Manipulator::getSegment () const;
//! \sreturn The working TrackElement.
//! \function DataNegociate* Manipulator::getData () const;
//! \sreturn The DataNegociate of the TrackElement (act as a cache).
//! \function RoutingEvent* Manipulator::getEvent () const;
//! \sreturn The RoutingEvent associated to the TrackElement (act as a cache).
//! \function bool Manipulator::canRipup ( unsigned int flags ) const;
//! \sreturn \true if the maximum ripup, for the given SegmentFsm::State has not
//! been reached. If \c flags contains Manipulator::HasNextRipup, return
//! \true \b only if it still have at least one ripup to go.
//! \function bool Manipulator::isCaged ( DbU::Unit axis ) const;
//! \sreturn \true if the segment is enclosed (in it's Track) by two fixed or
//! blockage segments which at least one is closer than 10 lambdas from
//! \c axis. Mostly used to know if a perpandicular is actually restricting
//! the axis span of a reference segment.
//! \function bool Manipulator::ripup ( unsigned int type, DbU::Unit axisHint=0 );
//! \param type The type of ripup action.
//! \param axisHint An indication as where to move the riped up segment.
//! \return \true if the operation has succedeed.
//!
//! If the TrackElement can be ripped up, schedule a ripup action, possibly
//! with a hint for the preferred axis position.
//! \function bool Manipulator::ripupPerpandiculars ( unsigned int flags );
//! Schedule a ripup of all the perpandiculars of the reference segment.
//! \c flags that modificate the behavior:
//! - Manipulator::PerpandicularsFirst : the queue will be reordered so
//! that all the perpandiculars are re-processed (placed) before the
//! reference segment.
//! - Manipulator::ToRipupLimit : the ripup count of the reference segment
//! is set to the limit (i.e. only one more attempt before a slackening
//! occurs).
//!
//! The method will fails (return \false) if at least one perpandicular can't
//! be changed of track (i.e. ripped up) \b and none of it's neighbors could
//! be ripped up either. Meaning that the free span on that track cannot be
//! changed.
//! \function void Manipulator::repackPerpandiculars ();
//! Ripup all the perpandiculars of the reference segment, except fixed or
//! globals. The reference segment is rescheduled first (before it's
//! perpandicular).
//!
//! This function may be used to find a better placement, maximizing the
//! overlap of the various perpandiculars.
//! \function bool Manipulator::ripple ();
//! \sreturn true if the reference segment is local.
//!
//! Applies only on reference segments that are of local type.
//! Tries to make room for the reference segment by ripping up it's neigbors
//! on the parallels tracks. On a vertical plane, left neigbors are shifted
//! one track left (trough axis hint) and right ones, one track right.
//! Note that they are ripped up and the shift is just a hint, there's no
//! guarantee that the router can honor it.
//! \function bool Manipulator::minimize ();
//! \sreturn true if the reference segment can be mimized in a suitable track hole.
//!
//! Compute the miminal span of the reference segment, summing up contraints
//! from source anchor and target anchors (if any) and perpandiculars.
//! Then find holes in the avalaible tracks, and check if one is suitable
//! for the miminized segment (try first the biggest hole).
//!
//! This operation can only be called once on a segment (a flag is set in the
//! event).
//! \function bool Manipulator::slacken ( unsigned int flags=KbNoFlags );
//! Simple proxy towards TrackElement::slacken().
//!
//! \red{To be reviewed.}
//! \function bool Manipulator::pivotUp ();
//! Tries to move up the reference segment. The segment will be moved
//! up only if a half track is free (for a local) or a full track is
//! free (for a global).
//!
//! This function do not modifies/create perpandiculars.
//! \function bool Manipulator::pivotDown ();
//! Tries to move down the reference segment. The segment will be moved
//! up only if \e two track are free (whether global or local). Is is more
//! restrictive than Manipulator::pivotUp().
//!
//! This function do not modifies/create perpandiculars.
//! \function bool Manipulator::moveUp ( unsigned int flags );
//! Tries to move up a segment, if there is enough space in the RoutingPlane
//! above and in the same direction.
//!
//! This function may modificate perpandiculars in order to maintain
//! connexity.
//!
//! \red{To be reviewed.}
//! \function bool Manipulator::makeDogleg ();
//! \sreturn \false if the segment is \e not local or the dogleg cannot be done.
//!
//! For \e local reference segment only, look in the first track candidate
//! for other segment overlapping and break the reference accordingly.
//! \function bool Manipulator::makeDogleg ( Interval overlap );
//! Create a dogleg to avoid the obstructed interval \c overlap.
//! \function bool Manipulator::makeDogleg ( DbU::Unit position );
//! Create a dogleg in the GCell under \c position.
//! \function bool Manipulator::relax ( Interval overlap, unsigned int flags=AllowExpand );
//! Break the reference segment so it can detour around the interval
//! \c overlap. If \c overlap is completly enclosed inside the span of
//! the reference segment two dogleg will be created. If the overlap occurs
//! only on one side of the reference segment, only one dogleg will be
//! created.
//!
//! If \c flags contains Manipulator::AllowExpand, the dogleg are not created
//! exactly at the edges of the overlap but on the lowest density GCell
//! (outside the overlap interval).
//!
//! The axis of the created dogleg are sets so that the broken part of the
//! segment completly enclose \c overlap. That is, the orignal segment no
//! longer intersect with \c overlap. So the min dogleg is pushed to the
//! left and the max to the right if they are in the same GCell as the
//! min/max of \c overlap. Otherwise (they have been expanded), they are
//! put in the center of the GCell.
//!
//! We do not allow to dogleg twice in the same GCell, so if min or max
//! is in respectively the first or last GCell, it is not done. Moreover
//! if there is only one dogleg \e and it is in the first or last GCell,
//! the relax method is cancelled (and returns \false). It means that
//! this is the segment which is likely to be enclosed inside \c overlap.
//!
//! \redB{Important:} The doglegs are created immediatly and not in a delayed
//! fashion like the SegmentAction.
//!
//! \image html ManipulatorRelax-1.png "Two Doglegs (min & max), no expansion"
//! \image html ManipulatorRelax-2.png "Two Doglegs (min & max), with expansion"
//! \image html ManipulatorRelax-3.png "One Dogleg (min)"
//! \image html ManipulatorRelax-4.png "One Dogleg (max)"
//! \function bool Manipulator::insertInTrack ( size_t i );
//! Try to insert the reference segment in the track at index \c i (in the cost
//! table from SegmentFsm). The insertion is done by ripping up overlapping
//! segment or shrinking them to left/right if possible.
//!
//! \red{This operation ripup the processed segment neighbors (and their perpandiculars).}
//! \function bool Manipulator::forceToTrack ( size_t i );
//! Try to insert the reference segment in the track at index \c i (in the cost
//! table from SegmentFsm). The insertion is done by \e forcibly ripping up the
//! overlapping segments \b and their perpandiculars.
//!
//! \red{This operation ripup the processed segment neighbors (and their perpandiculars).}
//! \function bool Manipulator::shrinkToTrack ( size_t i, unsigned int flags, DbU::Unit leftAxisHint, DbU::Unit rightAxisHint );
//! Attempt to minimize the reference segment to fit into the track.
//! For this operation to succeed, the minimal span of the segment must
//! not overlap any other segment already in the track. To reach the
//! minimal span the perpandiculars are ripped up with an axis hint
//! which is the center of the minimal span or the explicit value given
//! as arguments \c leftAxisHint and \c rightAxisHint if \c flags contains
//! respectively Manipulator::LeftAxisHint or Manipulator::RightAxisHint.
//!
//! \red{This operation ripup the processed segment itself and its perpandiculars.}
//! \function bool Manipulator::forceOverLocals ();
//! Loop over all the candidate tracks and, insert in the first which
//! all conflicting segments are locals (rip them up).
//! \function bool Manipulator::repackPerpandiculars ();
//! Ripup all perpandiculars and the reference segment itself for a complete
//! re-placement. The reference segment will be reprocessed \e before it's
//! perpandiculars.
}