coriolis/kite/doc/man/man3/Kite_RoutingEventQueue.3

.TH "RoutingEventQueue" 3 "Thu Nov 12 2020" "Version 1.0" "Kite - Detailed Router" \" -*- nroff -*-
.ad l
.nh
.SH NAME
RoutingEventQueue \- The priority Queue of \fBRoutingEvent\fP\&.  

.SH SYNOPSIS
.br
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBRoutingEventQueue\fP ()"
.br
.ti -1c
.RI "\fB~RoutingEventQueue\fP ()"
.br
.ti -1c
.RI "bool \fBempty\fP () const"
.br
.ti -1c
.RI "size_t \fBsize\fP () const"
.br
.ti -1c
.RI "unsigned int \fBgetTopEventLevel\fP () const"
.br
.ti -1c
.RI "\fBRoutingEvent\fP * \fBpop\fP ()"
.br
.ti -1c
.RI "void \fBload\fP (const vector< \fBTrackElement\fP *> &)"
.br
.ti -1c
.RI "void \fBadd\fP (\fBTrackElement\fP *, unsigned int level)"
.br
.ti -1c
.RI "void \fBpush\fP (\fBRoutingEvent\fP *)"
.br
.ti -1c
.RI "void \fBrepush\fP (\fBRoutingEvent\fP *)"
.br
.ti -1c
.RI "void \fBrepushInvalidateds\fP ()"
.br
.ti -1c
.RI "void \fBcommit\fP ()"
.br
.ti -1c
.RI "void \fBclear\fP ()"
.br
.in -1c
.SH "Detailed Description"
.PP 
The priority Queue of \fBRoutingEvent\fP\&. 


.SH "Implementation Details"
.PP
The \fBRoutingEventQueue\fP is build upon a STL multiset<> and is sorted according to the \fBRoutingEvent::Key\fP attribute of the event\&. The key attribute has been designed specifically to be used with this queue\&. It provides the features:
.IP "\(bu" 2
Sort the \fBRoutingEvent\fP according to their priority\&. Higher priority mainly means more constrained segment, which must be routed first\&.
.IP "\(bu" 2
The attributes of \fBRoutingEvent\fP may change while inserted in the queue\&. The key provide a cached value of those attributes ensuring a stable sorting order\&.
.PP
.PP
For more details about the sorting order, refer to \fBRoutingEvent::Key\fP\&.
.PP
\fBInsertion, Reinsertion & Commit\fP
.PP
When pushing a new event into the queue, the actual insertion into the multimap is delayed until the next call to \fCRoutingEvent::commit()\fP\&. The to be inserted events are stored into a request set which is processed when commit is called\&. At commit time, the \fBRoutingEvent::Key\fP cache is updated just before inserting the element\&.
.PP
When repushing an event, the event is immediatly withdrawn from the queue and put into the request set\&.
.PP
\fBMutiple Event for one Segment\fP
.PP
As \fBRoutingEvent\fP can be cloned, there may be more than one event pointing to a segment\&. But there must be \fIonly one active event\fP, the one which is pointed to by the segment\&. As a result, there maybe multiple events for an unique segment in the queue, but \fIonly one active event\fP, the one that will be processed\&. 
.SH "Constructor & Destructor Documentation"
.PP 
.SS "\fBRoutingEventQueue\fP ()"
Contructor, create an empty queue\&. 
.SS "~\fBRoutingEventQueue\fP ()"
Destructor\&.
.PP
\fBRemark: The destruction of the queue do not delete the\fP
.RS 4
\fBRoutingEvent\fP that may still be in it (they shouldn't an a warning is issued)\&. 
.RE
.PP

.SH "Member Function Documentation"
.PP 
.SS "bool empty () const\fC [inline]\fP"
\fBReturns:\fP \fBtrue\fP if there is the queue is empty\&. 
.SS "size_t size () const\fC [inline]\fP"
\fBReturns:\fP The number of events in the queue\&. 
.SS "unsigned int getTopEventLevel () const\fC [inline]\fP"
\fBReturns:\fP The greatest event level the queue has ever reached (always increasing, starting from zero)\&. 
.SS "\fBRoutingEvent\fP * pop ()"
Remove the top element of the queue (i\&.e\&. the one with the highest priority) and return it\&. If the queue is empty, \fCNULL\fP is returned\&. 
.SS "void load (const vector< \fBTrackElement\fP *> & segments)"
Load a whole vector of \fBTrackElement\fP into the queue, for each element:
.IP "\(bu" 2
Create a \fBRoutingEvent\fP linked to the element\&. To be reviewed: replace any previous event\&.
.IP "\(bu" 2
Insert the new \fBRoutingEvent\fP into the queue\&.
.PP
.PP
\fINo commit is needed after this operation\&.\fP 
.SS "void add (\fBTrackElement\fP * element, unsigned int level)"
Create a new \fBRoutingEvent\fP in the queue with \fClevel\fP, associated to \fCelement\fP\&. A commit is needed afterwards\&.
.PP
To be reviewed: replace any previous event on element\&. 
.PP
Referenced by NegociateWindow::addRoutingEvent()\&.
.SS "void push (\fBRoutingEvent\fP * event)\fC [inline]\fP"
Push a \fBRoutingEvent\fP in the queue\&. Effective only after the next commit\&. 
.PP
Referenced by RoutingEventQueue::add(), and RoutingEventQueue::repush()\&.
.SS "void repush (\fBRoutingEvent\fP * event)"
Force a complete queue re-insertion for \fCevent\fP\&. The event is immediatly withdrawn from the queue and put into the insertion request set\&.
.PP
If the \fCevent\fP is not already in the queue, works like \fBRoutingEventQueue::push()\fP\&. 
.PP
Referenced by RoutingEventQueue::repushInvalidateds(), and RoutingEvent::reschedule()\&.
.SS "void repushInvalidateds ()"
Using the list of invalidated segments from the \fBSession\fP, repush them if:
.IP "\(bu" 2
They have an associated event\&.
.IP "\(bu" 2
The event is not \fIunimplemented\fP, \fIdisabled\fP or \fIprocessed\fP\&. 
.PP

.PP
Referenced by RoutingEvent::process()\&.
.SS "void commit ()"
Process the insertion request set and actually insert it's elements into the queue\&. Perform a RoutingEvent::key update prior to insertion\&. 
.PP
Referenced by RoutingEvent::process()\&.
.SS "void clear ()"
Empty the queue\&. Issue a warning if the queue is not empty (i\&.e\&. some events remains to be processeds)\&. 
.PP
Referenced by RoutingEventQueue::~RoutingEventQueue()\&.

.SH "Author"
.PP 
Generated automatically by Doxygen for Kite - Detailed Router from the source code\&.