// -*- mode: C++; explicit-buffer-name: "Session.dox<katabatic>" -*-

 namespace Katabatic {

 /*! \class        Session
  *
  *  \brief        Modification Session for Katabatic
  *
  *                To perform modifications, the Katabatic data structure uses a session
  *                mechanism built on top of the Hurricane::UpdateSession one. Sessions
  *                obeys very simples rules:
  *                  - Only one Session can be opened at a time with Session::open().
  *                  - Subsequent calls to Session::open() returns the currently
  *                    opened session until Session::close() is called.
  *                  - Revalidation can take place whithout closing the Session by
  *                    calling Session::revalidate().
  *
  *                The task of a Session is to keep track of the AutoContact and
  *                AutoSegment that have been modificateds (i.e. invalidated) and,
  *                to restore connexity and/or topology when closed.
  *
  *                Two kinds of revalidation could be performed:
  *                <ul>
  *                  <li>\b Geometrical : only positions of AutoContacts and AutoSegments
  *                      extensions are recomputed.
  *                  <li>\b Topological : a whole net have been invalidated because of a
  *                      dogleg creation or a move up/move down of a segment.
  *                      <ul>
  *                        <li>\b Dogleg : needs to insert the newly created AutoSegments
  *                            and AutoContacts.
  *                        <li><b>Move up/Move down</b> : may needs to create additional
  *                            dogleg to restore connexity (gaps), and then insert them
  *                            like above.
  *                      </ul>
  *                      After a topological mofication has been done, the net needs to
  *                      be re-canonized then the geometrical step takes place.
  *                </ul>
  *
  *                The kind of revalidation needed is automatically detected by
  *                the Session.
  *
  *                In addition to it's main purpose, Session also provides cached
  *                access to frequently needed variables either from Hurricane
  *                or Katabatic Configuration and access to the AutoContact &
  *                AutoSegment LUTs of KatabaticEngine.
  *
  *                From a software point of view, Session is a singleton object.
  *
  *
  * \section       secSessionAlgo  Session Algorithm
  *
  *                Main attributes of a Session:
  *                - \c _netInvalidateds, nets on which topology has changed.
  *                - \c _autoSegments, that have been moved or createds.
  *                - \c _autoContacts, that have been created or one of their
  *                  slave segment has moved.
  *                - \c _revalidateds, the list of AutoSegments that have just
  *                  been revalidated (after calling \c revalidate()).
  *
  *                Schematic description of how a Session works:
  *
  *                <ul class="algo1">
  *                  <li> If at least one net has been invalidated, meaning that it's
  *                       topology has changed, perform \c _revalidateTopology().
  *                       <ul class="algo2">
  *                         <li> Update net topology: correct the topology of each
  *                              contacts, making dogleg when needed. The AutoContact
  *                              segment caching is updated at this point.
  *                         <li> Compute net constraints (on AutoContacts & AutoSegments).
  *                         <li> Compute net optimal positions (on AutoSegments).
  *                         <li> Compute the state of the segments regarding to terminals.
  *                         <li> Canonize sets of aligneds segments. The canonical segment
  *                              is the one with the lowest \c id.
  *                         <li> If the segments has just been created, put it on its
  *                              optimal axis.
  *                       </ul>
  *                       This stage can add itself more invalidated AutoSegments and
  *                       AutoContacts as it create doglegs.
  *
  *                   <li> Revalidate geometry of AutoContacts. That is, expand or shrink
  *                        the extremities of the invalidated AutoSegments. Note that
  *                        AutoSegments are already at on their final axis position.
  *
  *                   <li> Revalidate AutoSegments. Just before this stage, they are
  *                        on the correct axis and their extensions are also correct,
  *                        so we may update the caching of their characteristics
  *                        (mostly the extension).
  *                </ul>
  */

 //! \function     Session* Session::get ( const char* message=NULL );
 //!               Return the Session singleton, if no session is currently open
 //!               throw an exception carrying \c message.

 //! \function     Technology* Session::getTechnology ();
 //!               Hurricane shortcut.

 //! \function     KatabaticEngine* Session::getKatabatic ();
 //!               Katabatic shortcut.

 //! \function     const Configuration* Session::getConfiguration ();
 //!               Katabatic shortcut.

 //! \function     RoutingGauge* Session::getRoutingGauge ();
 //!               Katabatic shortcut.

 //! \function     unsigned int  Session::getLayerDirection ( const Layer* layer );
 //!               Returns the preferred routing direction of \c layer, as per defined
 //!               in the RoutingGauge.
 //!
 //! \remark       The value returned is transformed from the CRL Constants value
 //!               into Katabatic constants (Katabatic::KbHorizontal, Katabatic::KbVertical).

 //! \function     bool  Session::isInDemoMode ();
 //!               Katabatic shortcut.

 //! \function     float  Session::getSaturateRatio ();
 //!               Katabatic shortcut.

 //! \function     size_t  Session::getSaturateRp ();
 //!               Katabatic shortcut.

 //! \function     bool  Session::doWarnGCellOverload ();
 //!               Katabatic shortcut.

 //! \function     DbU::Unit  Session::getExtensionCap ();
 //!               Katabatic shortcut.

 //! \function     const Layer* Session::getRoutingLayer ( size_t );
 //!               Katabatic shortcut.

 //! \function     const Layer* Session::getContactLayer ( size_t );
 //!               Katabatic shortcut.

 //! \function     size_t  Session::getSegmentStackSize ();
 //! \sreturn      The number of AutoSegment in the invalidated stack.

 //! \function     size_t  Session::getContactStackSize ();
 //! \sreturn      The number of AutoSegment in the invalidated stack.

 //! \function     const vector<AutoSegment*>& Session::getInvalidateds (); 
 //! \sreturn      The stack (vector) of invalidateds AutoSegments.

 //! \function     const vector<AutoSegment*>& Session::getRevalidateds (); 
 //! \sreturn      The stack (vector) of AutoSegments that have been revalidateds.

 //! \function     const vector<AutoSegment*>& Session::getDoglegs (); 
 //! \sreturn      The vector of AutoSegments part of a newly created dogleg.
 //!               The dogleg creation functions in AutoHorizontal and AutoVertical
 //!               put a triplet (for example in horizontal direction \c (h1,v1,h2) )
 //!               for each dogleg composed of:
 //!                 - \b h1 the segment \e before the dogleg (which is also the original one).
 //!                 - \b v1 the segment \b perpandicular (new).
 //!                 - \b h2 the segment \b after (new).

 //! \function     const set<Net*>& Session::getNetsModificateds (); 
 //! \sreturn      The set of Nets that needs either a topological update or a new
 //!               canonization.

 //! \function     Session* Session::open ( KatabaticEngine* );
 //!               Opens a new session or returns the already opened one, if any.

 //! \function     void  Session::close ();
 //!               Close the Session, triggering the revalidation of the AutoSegemnts
 //!               and AutoContacts. If no Session is opened, throws an execption.

 //! \function     void  Session::setKatabaticFlags ( unsigned int );
 //!               Katabatic shortcut.

 //! \function     void  Session::dogleg ( AutoSegment* );
 //!               Adds an AutoSegment to the dogleg vector.

 //  \function     void  Session::doglegReset ();
 //                Clears the dogleg vector.

 //! \function     void  Session::revalidateTopology ();
 //!               Revalidate Net that have been invalidateds and re-canonize them.

 //! \function     void  Session::setInvalidateMask ( unsigned int flags );
 //!               Tells what kind of revalidation must be performed.

 //! \function     void  Session::invalidate ( Net* net );
 //!               Schedule \c net for a full revalidation, topological correction
 //!               and canonization.

 //! \function     void  Session::invalidate ( AutoSegment* segment );
 //!               Schedule \c segment for revalidation.

 //! \function     void  Session::invalidate ( AutoContact* contact );
 //!               Schedule \c contact for revalidation.

 //! \function     size_t  Session::revalidate ();
 //!               Perform the revalidation. Returns the sum of AutoContacts and
 //!               AutoSegemnts that have been revalidated.

 //! \function     void  Session::link ( AutoContact* ac );
 //!               Adds \c ac in the AutoContact lookup table (allow to retrieve an
 //!               AutoContact by it's base Contact).

 //! \function     void  Session::link ( AutoSegment* as );
 //!               Adds \c as in the AutoSegment lookup table (allow to retrieve an
 //!               AutoSegment by it's base Segment).

 //! \function     void  Session::unlink ( AutoContact* ac );
 //!               Removes \c ac from the AutoContact lookup table.

 //! \function     void  Session::unlink ( AutoSegment* as );
 //!               Removes \c as from the AutoSegment lookup table.

 //! \function     AutoContact* Session::lookup ( Contact* contact );
 //!               Lookup the AutoContact associated with \c contact. \c NULL if not found.

 //! \function     AutoSegment* Session::lookup ( Segment* segment );
 //!               Lookup the AutoSegment associated with \c segment. \c NULL if not found.

 }