// -*- 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& 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). //! //! Cloning Management. 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). //! //! Unimplemented Protection. If the unimplemented flag is set the reschedule //! is cancelled (\c NULL is returned). //! //! Unprocessed Event. The event is still in queue, waiting to be //! processed, then just repush it in the queue with it's new level. //! //! Processed Event. Clone the already processed one, activate it //! and push it on the queue. //! //! Router's Mode. 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). }