170 lines
8.5 KiB
C++
170 lines
8.5 KiB
C++
// -*- mode: C++; explicit-buffer-name: "Session.dox<kite>" -*-
|
|
|
|
|
|
namespace Kite {
|
|
|
|
/*! \class Session
|
|
* \brief Kite update Session
|
|
*
|
|
* Session extend the Katabatic update session to the Kite
|
|
* router level. Mainly by managing Track update.
|
|
*
|
|
* <b>Difference between Kite & Katabatic sessions:</b>
|
|
* - 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.
|
|
*
|
|
* <b>Asymmetry between invalidation & revalidation:</b>
|
|
* - 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.
|
|
*
|
|
* <b>Indirect TrackSegment invalidation:</b>
|
|
* - 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. <b>This is the time TrackSegment
|
|
* are moved into their new Track (physical displacement)</b>.
|
|
* 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.
|
|
*
|
|
* <b>Note:</b> 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.
|
|
*
|
|
* <b>Note:</b> 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.
|
|
|
|
|
|
}
|