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