// -*- C++ -*-
namespace Kite {
/*! \class RoutingEvent::Key
* \brief RoutingEvent cached key for maps
*
* The key is used as a cache in RoutingEvent, that is, the RoutingEvent
* attributes could be modificated without the key changing. It is
* important for the key to remain stable as it used in the various
* event queue as the sorting attribute. The key should be updated
* only when the RoutingEvent is temporarily whidrawn from the queue.
*
* Cached attributes: (used in that lexicographical order for sorting)
* - \b 1 -- \c eventLevel.
* - \b 2 -- \c canRipple.
* - \b 3 -- \c priority.
* - \b 4 -- \c length.
* - \b 5 -- \c isHorizontal.
* - \b 6 -- \c axis.
* - \b 7 -- \c sourceU.
* - \b 8 -- \c net (name).
* - \b 9 -- \c id.
* - \b X -- \c slackenStrap \b unused.
* - \b X -- \c tracksNb \b unused.
*
* It is internally managed by RoutingEvent and the queue.
*/
//! \function RoutingEvent::Key::update ( const RoutingEvent* event );
//! Cache the value of the key from \c event.
/*! \class RoutingEvent
* \brief Atomic Placement Request for a TrackSegment
*
* \red{The trackFrees attribute has to be reviewed not sure it's still useful.}
*
* Cached key for stable sorting, see RoutingEvent::Key.
*/
//! \enum RoutingEvent::Mode
//! The working mode of the router, affect how events are to
//! be handled.
//! \var RoutingEvent::Negociate
//! This is the normal mode of operation, topological modifications
//! and ripup are enableds.
//! \var RoutingEvent::Pack
//! First post-processing step. For each segment, tries to find a
//! more compact position for a segment, but without riping any others.
//! \var RoutingEvent::Repair
//! Second post-processing step, try to find a suitable location for
//! a segment more aggressively.
//! \function unsigned int RoutingEvent::getStage ();
//! \sreturn The stage the router is in (see RoutingEvent::Mode).
//! \function size_t RoutingEvent::getAllocateds ();
//! \sreturn The number of RoutingEvent currently allocateds.
//! \function size_t RoutingEvent::getProcesseds ();
//! \sreturn The number of RoutingEvent that have been processeds since
//! the last call to RoutingEvent::resetProcesseds().
//! \function void RoutingEvent::resetProcesseds ();
//! \sreturn Reset the number of processeds events.
//! \function unsigned int RoutingEvent::setStage ( unsigned int mode );
//! Sets the router's stage (see RoutingEvent::Mode).
//! \function RoutingEvent* RoutingEvent::create ( TrackElement* element, unsigned int mode );
//! \param element The element for which to create the event.
//! \param mode The mode into which this event will be valid.
//!
//! RoutingEvent constructor.
//! \function RoutingEvent* RoutingEvent::clone () const;
//! \return A clone of the event.
//!
//! Cloning an event is slightly different from copying it (which is forbidden).
//! There can be multiple events for one \c element but only one must be
//! active at a time. This is a cheap way of implementing the rescheduling
//! mechanism. The original event remains the active one, but it's cloned
//! flag is raised. The cloned event is created inactive and with a null
//! \e eventLevel.
//! \function void RoutingEvent::destroy ();
//! The destructor.
//! \function bool RoutingEvent::isCloned () const;
//! \sreturn \true if this event has been cloned at least once.
//! \function bool RoutingEvent::isValid () const;
//! \sreturn \true if the cached informations from the \e element are valid
//! (i.e. the element has not been changed).
//! \function bool RoutingEvent::isUnimplemented () const;
//! \sreturn \true if the event has tried to use an unimplemented feature.
//! \function bool RoutingEvent::isProcessed () const;
//! \sreturn \true if the event has been processed.
//! \function bool RoutingEvent::isDisabled () const;
//! \sreturn \true if the event is \b not the active one. It should be discarted
//! by the algorithm.
//! \function bool RoutingEvent::isForcedToHint () const;
//! \sreturn \true the \e element must be placed exacltly on the given axis hint.
//! \function bool RoutingEvent::isRipedByLocal () const;
//! \sreturn \true the \e element (global) has been riped up to place a local one.
//! \function bool RoutingEvent::canMinimize () const;
//! \sreturn \true the \e element could still be minimized.
//! \function unsigned int RoutingEvent::getMode () const;
//! \sreturn the mode the event must be taken into account to.
//! \function unsigned int RoutingEvent::getState () const;
//! \sreturn the mode the router is currently in.
//! \function const Key& RoutingEvent::getKey () const;
//! \sreturn The \e key to use in map & queue for this event.
//! \function TrackElement* RoutingEvent::getSegment () const;
//! \sreturn The associated segment.
//! \function const vector<TrackElement*>& RoutingEvent::getPerpandiculars () const;
//! \sreturn A vector of cached perpandiculars to the associated segment.
//! \function DbU::Unit RoutingEvent::getAxisHint () const;
//! \sreturn The preferred position for the segment axis.
//! \function DbU::Unit RoutingEvent::getAxisHistory () const;
//! \sreturn The previous position of the segment axis (before it's current position).
//! \function DbU::Unit RoutingEvent::getAxisWeight ( DbU::Unit axis ) const;
//! \sreturn The distance between \c axis and the preferred position.
//! \function const Interval& RoutingEvent::getOptimal () const;
//! \sreturn The range of positions for the optimal axis (cached).
//! \function const Interval& RoutingEvent::getConstraints () const;
//! \sreturn The range of legal positions for the axis.
/*! \function unsigned int RoutingEvent::getPriority () const;
* \sreturn The priority of the event, it quantify the degree of freedom of the
* segment. Currently it's computed from the length of the segment
* and it's slack:
\f[
priority = (slack(segment)+1.0) \times (length(segment)+1.0)
\f]
* A high priority means that the segment will be harder to place
* thus it will be scheduled first. With this function, longer
* segments will be placed first.
*/
//! \function unsigned int RoutingEvent::getEventLevel () const;
//! \sreturn The event level of the event, used to tweak the order inside the event
//! queue. It differs from the priority in the sense that it isn't a
//! topologicaly based value, but manipulated by the algorithm.
//! \function unsigned int RoutingEvent::getTracksNb () const;
//! \sreturn The number of tracks avalaibles for the segment to be placed.
//! \function unsigned int RoutingEvent::getInsertState () const;
//! \return The kind of track insertion that will be intended. It's a counter
//! whose values have the following meaning:
//! - \b 1 : normal insert.
//! - \b 2 : shrink the segment to it's minimum before inserting.
//! - \b 3 : attempt to ripup conflicting others before inserting.
//! \function void RoutingEvent::revalidate ();
//! Perform an event revalidation.
//! \function void RoutingEvent::updateKey ();
//! Update the key with the new values from the event, the key \e must
//! not be inserted in the queue when this method is called.
//! \function void RoutingEvent::process ( RoutingEventQueue& queue, RoutingEventHistory& history, RoutingEventLoop& loop );
//! \param queue The main event queue.
//! \param history The event's history list.
//! \param loop The loop detector.
//!
//! Process the event, that is:
//! - First, check if there is no looping, if any, do not process the
//! event but dicard it (marked as unimplemented).
//! - Second, attempt to place the associated segment. Pass it to the relevant
//! function, according to the router's mode (\c _processNegociate(),
//! \c processPack() or \c _processRepair() ).
//! Once processed, the event is added to both \c history (for the record)
//! and \c loop to check if we are not looping.
//! \function void RoutingEvent::setSegment ( TrackElement* element );
//! Change the associated \c segment. \red{Used only by TrackSegment::swapTrack().}
//! \function RoutingEvent* RoutingEvent::reschedule ( RoutingEventQueue& queue, unsigned int eventLevel);
//! \return The newly reinserted event. Depending on the cases it could be itself.
//!
//! Insert or reinsert an event in the scheduler. The \c eventLevel parameter only
//! allows to increase the level (if it is less than the current level of the
//! event, it will be ignored).
//!
//! <b>Cloning Management.</b> As an event could be cloned, if we try to re-insert
//! a disabled original, we must first lookup the currently cloned active event.
//! This is done through the associated \c segment which must always be associated
//! with the active event (if any).
//!
//! <b>Unimplemented Protection.</b> If the unimplemented flag is set the reschedule
//! is cancelled (\c NULL is returned).
//!
//! <b>Unprocessed Event.</b> The event is still in queue, waiting to be
//! processed, then just repush it in the queue with it's new level.
//!
//! <b>Processed Event.</b> Clone the already processed one, activate it
//! and push it on the queue.
//!
//! <b>Router's Mode.</b> The mode is also updated.
//! \function void RoutingEvent::setMode ( unsigned int mode );
//! Set the mode in which the event must be processed (see RoutingEvent::Mode).
//! \function void RoutingEvent::setState ( unsigned int state );
//! Proxy mutator for DataNegociate::setState().
//! \function void RoutingEvent::setAxisHintFromParent ();
//! Sets the axis hint from it's parent segment. The parentage is found
//! through the TrackSegment parentage.
//! \function void RoutingEvent::incInsertState ();
//! Increment the insertion state.
//!
//! \sa RoutingEvent::getInsertState().
//! \function void RoutingEvent::resetInsertState ();
//! Reset the insertion state.
//!
//! \sa RoutingEvent::getInsertState().
//! \function void RoutingEvent::setEventLevel ( unsigned int level );
//! Set the event level (user-controlled re-ordering).
}