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