coriolis/kite/doc/RoutingEvent.dox

 // -*- 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).

 }