00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright 2007 University of Washington 00004 * 00005 * This program is free software; you can redistribute it and/or modify 00006 * it under the terms of the GNU General Public License version 2 as 00007 * published by the Free Software Foundation; 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 * 00018 * Author: Craig Dowell (craigdo@ee.washington.edu) 00019 */ 00020 00021 #ifndef CANDIDATE_QUEUE_H 00022 #define CANDIDATE_QUEUE_H 00023 00024 #include <stdint.h> 00025 #include <list> 00026 #include "ns3/ipv4-address.h" 00027 00028 namespace ns3 { 00029 00030 class SPFVertex; 00031 00032 /** 00033 * \brief A Candidate Queue used in static routing. 00034 * 00035 * The CandidateQueue is used in the OSPF shortest path computations. It 00036 * is a priority queue used to store candidates for the shortest path to a 00037 * given network. 00038 * 00039 * The queue holds Shortest Path First Vertex pointers and orders them 00040 * according to the lowest value of the field m_distanceFromRoot. Remaining 00041 * vertices are ordered according to increasing distance. This implements a 00042 * priority queue. 00043 * 00044 * Although a STL priority_queue almost does what we want, the requirement 00045 * for a Find () operation, the dynamic nature of the data and the derived 00046 * requirement for a Reorder () operation led us to implement this simple 00047 * enhanced priority queue. 00048 */ 00049 class CandidateQueue 00050 { 00051 public: 00052 /** 00053 * @brief Create an empty SPF Candidate Queue. 00054 * @internal 00055 * 00056 * @see SPFVertex 00057 */ 00058 CandidateQueue (); 00059 00060 /** 00061 * @internal Destroy an SPF Candidate Queue and release any resources held 00062 * by the contents. 00063 * @internal 00064 * 00065 * @see SPFVertex 00066 */ 00067 virtual ~CandidateQueue (); 00068 00069 /** 00070 * @brief Empty the Candidate Queue and release all of the resources 00071 * associated with the Shortest Path First Vertex pointers in the queue. 00072 * @internal 00073 * 00074 * @see SPFVertex 00075 */ 00076 void Clear (void); 00077 00078 /** 00079 * @brief Push a Shortest Path First Vertex pointer onto the queue according 00080 * to the priority scheme. 00081 * @internal 00082 * 00083 * On completion, the top of the queue will hold the Shortest Path First 00084 * Vertex pointer that points to a vertex having lowest value of the field 00085 * m_distanceFromRoot. Remaining vertices are ordered according to 00086 * increasing distance. 00087 * 00088 * @see SPFVertex 00089 * @param vNew The Shortest Path First Vertex to add to the queue. 00090 */ 00091 void Push (SPFVertex *vNew); 00092 00093 /** 00094 * @brief Pop the Shortest Path First Vertex pointer at the top of the queue. 00095 * @internal 00096 * 00097 * The caller is given the responsiblity for releasing the resources 00098 * associated with the vertex. 00099 * 00100 * @see SPFVertex 00101 * @see Top () 00102 * @returns The Shortest Path First Vertex pointer at the top of the queue. 00103 */ 00104 SPFVertex* Pop (void); 00105 00106 /** 00107 * @brief Return the Shortest Path First Vertex pointer at the top of the 00108 * queue. 00109 * @internal 00110 * 00111 * This method does not pop the SPFVertex* off of the queue, it simply 00112 * returns the pointer. 00113 * 00114 * @see SPFVertex 00115 * @see Pop () 00116 * @returns The Shortest Path First Vertex pointer at the top of the queue. 00117 */ 00118 SPFVertex* Top (void) const; 00119 00120 /** 00121 * @brief Test the Candidate Queue to determine if it is empty. 00122 * @internal 00123 * 00124 * @returns True if the queue is empty, false otherwise. 00125 */ 00126 bool Empty (void) const; 00127 00128 /** 00129 * @brief Return the number of Shortest Path First Vertex pointers presently 00130 * stored in the Candidate Queue. 00131 * @internal 00132 * 00133 * @see SPFVertex 00134 * @returns The number of SPFVertex* pointers in the Candidate Queue. 00135 */ 00136 uint32_t Size (void) const; 00137 00138 /** 00139 * @brief Searches the Candidate Queue for a Shortest Path First Vertex 00140 * pointer that points to a vertex having the given IP address. 00141 * @internal 00142 * 00143 * @see SPFVertex 00144 * @param addr The IP address to search for. 00145 * @returns The SPFVertex* pointer corresponding to the given IP address. 00146 */ 00147 SPFVertex* Find (const Ipv4Address addr) const; 00148 00149 /** 00150 * @brief Reorders the Candidate Queue according to the priority scheme. 00151 * @internal 00152 * 00153 * On completion, the top of the queue will hold the Shortest Path First 00154 * Vertex pointer that points to a vertex having lowest value of the field 00155 * m_distanceFromRoot. Remaining vertices are ordered according to 00156 * increasing distance. 00157 * 00158 * This method is provided in case the values of m_distanceFromRoot change 00159 * during the routing calculations. 00160 * 00161 * @see SPFVertex 00162 */ 00163 void Reorder (void); 00164 00165 private: 00166 /** 00167 * Candidate Queue copy construction is disallowed (not implemented) to 00168 * prevent the compiler from slipping in incorrect versions that don't 00169 * properly deal with deep copies. 00170 */ 00171 CandidateQueue (CandidateQueue& sr); 00172 00173 /** 00174 * Candidate Queue assignment operator is disallowed (not implemented) to 00175 * prevent the compiler from slipping in incorrect versions that don't 00176 * properly deal with deep copies. 00177 */ 00178 CandidateQueue& operator= (CandidateQueue& sr); 00179 00180 typedef std::list<SPFVertex*> CandidateList_t; 00181 CandidateList_t m_candidates; 00182 }; 00183 00184 } // namespace ns3 00185 00186 #endif /* CANDIDATE_QUEUE_H */