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