coriolis/kite/doc/Session.dox

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


 }