
 // -*- C++ -*-


 namespace Katabatic {

 /*! \defgroup     katabaticSession 7. Katabatic update Session Mechanism (internal)
  *
  *                This module documents the Katabatic update Session Mechanism.
  *                It is intented for developpers only.
  *
  *
  *  \section      secSessionGoal Goal of The Katabatic::Session
  *
  *                Due to obvious performance issue, we do not recompute the
  *                geometry of source and target of a Katabatic::AutoSegment
  *                each time it's moved by the router. Instead we uses a simple
  *                queuing mechanism : the Katabatic::Session.
  *
  *                Note that, most of the time, the router only moves segments,
  *                that is, never modifies directly Katabatic::AutoContact.
  *                The only exceptions being during the initial building stage
  *                or when the router decide to change the topology of a net.
  *                
  *                The router knows which Katabatic::AutoSegment it has moved,
  *                but during the update of a Katabatic::AutoContact geometry
  *                more segments will be modified. The modification being a
  *                change in their soure and/or target extention. And of thoses
  *                the router will not know about. To solve this problem,
  *                the router has to set a callback Katabatic::SegmentRevalidateCB
  *                which will be called for each modificated Katabatic::AutoSegment.
  *
  *                Note that, in order to uniformize the procedure, this callback
  *                will also be run on Katabatic::AutoSegment modificated by
  *                the router.
  *
  *
  *  \section      secSectionLookup The lookup function.
  *
  *                To find a Katabatic::AutoSegment from it's associated \Hurricane
  *                segment, we build a simple \STL map in the Katabatic \c ToolEngine.
  *                This lookup table, can be accessed through the Session lookup()
  *                function, once the session is open.
  *
  *              
  *  \section      secSessionRevalidate The Revalidate procedure
  *              
  *                The sequence of calls is as follow :
  *                <ol>
  *                  <li>The Router modifies some Katabatic::AutoSegment by moving
  *                      their axis. For example, horizontal segments in an horizontal
  *                      routing channel.
  *                  <li>The Katabatic::AutoSegment is then invalidated : put in the
  *                      invalidated segment set. It's Katabatic::AutoContact anchors
  *                      are also invalidated and put in the set of invalidated contacts.
  *                  <li>At some point, a global revalidation is performed :
  *                      Katabatic::Session::revalidate(). Says, when the channel
  *                      is successfully routed.
  *                  <li>Katabatic::updateGeometry() is called and update the
  *                      geometry of all invalided Katabatic::AutoContact. Doing so
  *                      almost surely leads to the invalidation of more Katabatic::AutoSegment
  *                      which are added to the invalidated set. In this example, as
  *                      we moved horizontal segments, the new invalidated segments
  *                      will be vertical ones incident to the formers.
  *                  <li>Finally we call Katabatic::AutoSegment::onRevalidate()
  *                      fonction for each Katabatic::AutoSegment.
  *                      This function encapsulate the callback from the router, so it
  *                      can take into account the segment extension change.
  *                </ol>
  *              
  *                \image html  AutoInvalidate-1.png "Revalidate Procedure"
  *                \image latex AutoInvalidate-1.pdf "Revalidate Procedure" width=0.9\textwidth
  *
  *
  *  \section      secStaticAccess  The Static Member choice
  *
  *                Almost all Session function members are \c static, this is
  *                because they refers to the currently opened Session which is
  *                kept entirely internal to the \c KatabaticSession module.
  *                This avoid carrying a global variable for the Session object.
  */


 /*! \class        Session
  *  \brief        Katabatic update Session (\b API).
  *
  *                The Katabatic Session is mandatory before any AutoSegment /
  *                AutoContact to be modified (supposedly by a router).
  *
  *                Unlike \Hurricane \c update \c Session only one session
  *                can be opened at a time (no stacking mechanism). Opening a
  *                Katabatic update Session also opens an \Hurricane \c update
  *                \c Session.
  *
  *                For details on how Katabatic Sessions works, have a look to
  *                \ref katabaticSession.
  */

 /*! \function     static Session* Session::get ();
  *  \return       The currently opened session, \c NULL if no session has
  *                been opened.
  */

 /*! \function     static Katabatic* Session::getKatabatic ();
  *  \return       The Katabatic ToolEngine associated to the current update
  *                session.
  */

 /*! \function     static AutoSegment* Session::lookup ( Segment* segment );
  *  \param        segment An \Hurricane segment.
  *  \return       The associated Katabatic AutoSegment.
  *
  *                For this function to work, a Katabatic Session must be opened
  *                as it's a simple bypass to the Katabatic::_Lookup() member.
  */

 /*! \function     static Session* Session::open ( KatabaticEngine* ktbt );
  *  \param        ktbt A Katabatic ToolEngine on which to work.
  *
  *                Open a new Katabatic update Session on the \c ktbt \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     static size_t  Session::close ();
  *  \return       The number of AutoContact / AutoSegment that have been revalidateds.
  *
  *                Ends an update Session. This functions made a call to Revalidate to
  *                ensure that no AutoContact / AutoSegment remains invalidated.
  */

 /*! \function     static size_t  Session::revalidate ();
  *  \return       The number of AutoContact / AutoSegment that have been revalidateds.
  *
  *                Revalidate all AutoContact / AutoSegment currently in the queue :
  *                that is, update the AutoContact geometry and AutoSegment extentions.
  */

 /*! \function     void  Session::invalidate ( AutoSegment* segment );
  *  \param        segment An AutoSegment that has been moved.
  *
  *                The invalidated AutoSegment are stored into a \STL set,
  *                so it can be added multiples times without problems.
  */

 /*! \function     void  Session::invalidate ( AutoContact* contact );
  *  \param        contact An AutoContact of which a AutoSegment has been moved.
  *
  *                The invalidated AutoContact are stored into a \STL set,
  *                so it can be added multiples times without problems.
  */

 }
