// -*- mode: C++; explicit-buffer-name: "Session.dox" -*- namespace Kite { /*! \class Session * \brief Kite update Session * * Session extend the Katabatic update session to the Kite * router level. Mainly by managing Track update. * * Difference between Kite & Katabatic sessions: * - In Katabatic, segments are actually moved \e before the * revalidation, then \e during the revalidation, contacts * and topologies are adjusteds * - In Kite, nothing is moved until the revalidation. * Requests for segment displacement are queued for the session. * * Asymmetry between invalidation & revalidation: * - When a TrackSegment (or directly an AutoSegment) is invalidated * both associated AutoSegment and TrackSegment are invalidated * (through the Observer mechanism). * - When an AutoSegment is revalidated, the TrackSegment is \b not * immediatly revalidated. See the revalidate algorithm for more * details. * * Indirect TrackSegment invalidation: * - TrackSegment invalidation do not result only from direct insertion * in Track. For example, any or all of it's perpandicular can be * invalidated trough the Katabatic::Session update (the perpandicular * Katabatic::AutoSegment is revalidated, generating invalidation on their * associated TrackSegment). * * For details on how Katabatic Sessions works, have a look to * Katabatic::Session. * * * \section secSessionMechanism The Session Mechanism. * * Delayed modification procedure : * - Modifications events are recorded (queued) into the Session. * At this step, no modification are actually done, the * data-base retains it's previous state and coherency. * - The \c revalidate() procedure is called (or the Session * is closed), then all the modification events are applied. * The data-base is in now in it's new state. * * * \section secKiteSessionRevalidate The Revalidate Algorithm. * * Revalidation steps : * - Process all remove events. detach TrackSegment from * their Track, but do not remove the pointer from the * internal \vector. * - Pack all Track in which removal have took place. * - Process all insert events. This is the time TrackSegment * are moved into their new Track (physical displacement). * It is at this point that the invalidation of both AutoSegment * and TrackSegment is done. * - Call the Katabatic::Session::revalidate() method which * will recompute the correct contact extensions and topologies. * \e After this step the Katabatic data-base is up to date, * but \e not the Kite one. AutoSegment are revalidated. * - Recompute the canonical position of source and target * of all invalidateds TrackSegment (take account of * extention modifications). The set of invalidated TrackSegment * is computed from the revalidated AutoSegment, that is * AutoSegment that are canonical. * - Perform a sort() on all Track that have been modifieds. * - Now that the size of the segments have been accurately computed, * look for revalidateds TrackSegment that: * -# Can be reduced, generate a track remove event. * -# Must be raised, generate a routing event (put into the * queue). * - Process the additional track remove events. * * Note: We cannot use the Observer mechanism to automatically * update TrackSegment from an AutoSegment, because we must wait for all * AutoSegments (canonical or not) involved into the TrackSegment to be * up to date before we can update it. * * Note: Have to talk about the special case when new canonical * AutoSegment appears after dogleg creation. * * * \section secKiteSessionLookup The Lookup Mechanism * * There are two lookup mechanisms: * - From a Hurricane::Segment, we uses the Katabatic segment lookup * table (slow, stored in a \c map<>). * - From a Katabatic::AutoSegment, we uses the Observer, it's owner * is the TrackSegment (fast). */ //! \function Session* Session::open ( KiteEngine* kite ); //! \param kite A Kite ToolEngine on which to work. //! \return A new Kite update Session. //! //! Open a new Kite update Session on the \c kite \c ToolEngine. //! At this point only one session can be opened at a time. Attempt //! to open a second one will result in an exception. //! \function Session* Session::get ( const char* message=NULL ); //! \sreturn The currently opened session, \c NULL if no session has //! been opened. //! \function Katabatic::Session* Session::base (); //! \sreturn The Session, casted as it's base object. //! \function bool Session::isEmpty (); //! Ensure that the Session is empty and can be closed (deleted) //! safely. //! \function Configuration* Session::getConfiguration (); //! \sreturn The Kite Configuration of the Router (proxy helper). //! \function Net* Session::getBlockageNet (); //! \sreturn The net used to create blockage components (proxy helper). //! \function KiteEngine* Session::getKiteEngine (); //! \sreturn The Kite ToolEngine associated to the current update //! session (proxy helper). //! \function NegociateWindow* Session::getNegociateWindow (); //! \sreturn The current NegociateWindow (proxy helper). //! \function Katabatic::GCell* Session::getGCellUnder ( DbU::Unit x, DbU::Unit y ); //! \sreturn The GCell under \c (x,y) (proxy helper, see Katabatic::GCellGrid::getGCell()). //! \function void Session::addInsertEvent ( TrackElement* segment, Track* track ); //! \param segment An AutoSegment to insert in a Track. //! \param track The Track into which the \e segment will be inserted. //! //! Schedule the insertion of \e segment into Track \e track. //! The \e segment must not already be part of a Track. //! \function void Session::addRemoveEvent ( TrackElement* segment ); //! \param segment A TrackSegment to remove from a Track. //! //! Schedule the removal of \e segment from Track \e track. //! \function void Session::addMoveEvent ( TrackElement* segment, Track* track ); //! \param segment An AutoSegment to move into a new Track. //! \param track The Track into which the \e segment will be moved. //! //! Schedule the displacement of \e segment into Track \e track. //! \function void Session::addSortEvent ( Track* track, bool forced=false ); //! \param track The Track to update. //! \param forced Force the invalidation of the \Track. //! //! Schedule the update of Track \e track. If the \Track has not been //! invalidated, no actual sort will takes place. To force a sort //! (manually invalidating the \Track), sets \b forced to \true. //! //! \sa Track::pack() & Track::sort(). //! \function void Session::revalidate (); //! Applies all the requested modifications, but keeping the session //! opened. //! \function TrackElement* Session::lookup ( Segment* segment ); //! \sreturn the TrackElement associated to \c segment. //! \function TrackElement* Session::lookup ( AutoSegment* segment ); //! \sreturn the TrackElement associated to \c segment. }