A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
nix-vector.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 The Georgia Institute of Technology
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License version 2 as
6 * published by the Free Software Foundation;
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 *
17 * Authors: Josh Pelkey <jpelkey@gatech.edu>
18 */
19
20#ifndef NIX_VECTOR_H
21#define NIX_VECTOR_H
22
23#include "buffer.h"
24
25#include "ns3/ptr.h"
26#include "ns3/simple-ref-count.h"
27
28namespace ns3
29{
30
31/**
32 * \ingroup packet
33 *
34 * \brief Neighbor-index data structure for nix-vector routing
35 *
36 * This data structure holds a vector of "neighbor-indexes" for
37 * a simulation specific routing protocol, nix-vector routing.
38 * These neighbor-indexes correspond to the net-device which a
39 * node should use to route a packet. A nix-vector is built
40 * (or fetched from a cache) on-demand. The nix-vector is
41 * transmitted with the packet, and along each hop of the
42 * route, the current node extracts the appropriate
43 * neighbor-index and routes the packet.
44 *
45 * \internal
46 * The implementation of NixVector uses a vector to store
47 * the neighbor-indexes. Each entry in the vector is 32
48 * bits long and can store multiple neighbor-indexes. A
49 * fair amount of bit manipulation is used to store these
50 * neighbor-indexes efficiently. A vector is used so that
51 * the nix-vector can grow arbitrarily if the topology and
52 * route requires a large number of neighbor-indexes.
53 *
54 * As the nix-vector travels along the route, an internal
55 * private member variable keeps track of how many bits
56 * have been used. At a particular node, the nix-vector
57 * is used to return the next neighbor-index. This
58 * neighbor-index is used to determine which net-device
59 * to use. The number of bits used would then be
60 * incremented accordingly, and the packet would be
61 * routed.
62 */
63
64class NixVector : public SimpleRefCount<NixVector>
65{
66 public:
67 NixVector();
68 ~NixVector();
69 /**
70 * \return a copy of this nix-vector
71 */
72 Ptr<NixVector> Copy() const;
73 /**
74 * \param o the NixVector to copy to a new NixVector
75 * using a constructor
76 */
77 NixVector(const NixVector& o);
78 /**
79 * \return a reference to the assignee
80 *
81 * \param o the NixVector to copy to a new NixVector using the
82 * equals operator
83 */
84 NixVector& operator=(const NixVector& o);
85 /**
86 * \param newBits the neighbor-index to be added to the vector
87 * \param numberOfBits the number of bits that newBits contains
88 *
89 * Adds the neighbor index to the vector using a fair amount of
90 * bit manipulation to pack everything in efficiently.
91 *
92 * Note: This function assumes that the number of bits to be added
93 * is always less than or equal to 32, ie., you can only span one
94 * entry of a nix-vector at a time. This is reasonable, since 32
95 * bits gives you 2^32 possible neighbors.
96 */
97 void AddNeighborIndex(uint32_t newBits, uint32_t numberOfBits);
98 /**
99 * \return the neighbor index
100 *
101 * \param numberOfBits the number of bits to extract from the vector
102 *
103 * Extracts the number of bits specified from
104 * the vector and returns the value extracted
105 *
106 * Note: This function assumes that the number of bits to be extracted
107 * is always less than or equal to 32, ie., you can only span one
108 * entry of a nix-vector at a time. This is reasonable, since 32
109 * bits gives you 2^32 possible neighbors.
110 */
112 /**
113 * \return number of bits remaining in the
114 * nix-vector (ie m_total - m_used)
115 */
117 /**
118 * \return the number of bytes required for serialization
119 */
121 /**
122 * \return zero if buffer not large enough
123 *
124 * \param buffer points to serialization buffer
125 *
126 * \param maxSize max number of bytes to write
127 *
128 * This nix-vector is serialized into the raw character
129 * buffer parameter.
130 */
131 uint32_t Serialize(uint32_t* buffer, uint32_t maxSize) const;
132 /**
133 * \return zero if a complete nix-vector is not deserialized
134 *
135 * \param buffer points to buffer for deserialization
136 *
137 * \param size number of bytes to deserialize
138 *
139 * The raw character buffer containing all the nix-vector
140 * information is deserialized into this nix-vector.
141 */
142 uint32_t Deserialize(const uint32_t* buffer, uint32_t size);
143 /**
144 * \return number of bits of numberOfNeighbors
145 *
146 * \param numberOfNeighbors the total number of neighbors
147 *
148 * This function is used to determine the number of bits of
149 * numberOfNeighbors so that this value can be passed in to
150 * AddNeighborIndex or ExtractNeighborIndex.
151 */
152 uint32_t BitCount(uint32_t numberOfNeighbors) const;
153
154 /**
155 * Set the NixVector Epoch
156 * \param epoch the NixVector Epoch
157 */
158 void SetEpoch(uint32_t epoch);
159
160 /**
161 * Get the NixVector Epoch
162 * \return the NixVector Epoch
163 */
164 uint32_t GetEpoch() const;
165
166 private:
167 /// Typedef: the NixVector bits storage.
168 typedef std::vector<uint32_t> NixBits_t;
169
170 /**
171 * \brief Print the NixVector.
172 *
173 * \param os the output stream
174 *
175 * \note: this could be greatly simplified by using std::format (but it's C++20).
176 */
177 void DumpNixVector(std::ostream& os) const;
178
179 /**
180 * \brief Stream insertion operator.
181 *
182 * \param os the stream
183 * \param nix the Nixvector
184 * \returns a reference to the stream
185 */
186 friend std::ostream& operator<<(std::ostream& os, const NixVector& nix);
187
188 NixBits_t m_nixVector; //!< the actual nix-vector
189 uint32_t m_used; //!< For tracking where we are in the nix-vector
190
191 /**
192 * A counter of how total bits are in
193 * the nix-vector
194 */
196
197 uint32_t m_epoch; //!< Epoch of the Nix-vector creation
198
199 /**
200 * Internal for pretty printing of nix-vector (no fill)
201 * \param decimalNum decimal divider
202 * \param bitCount bit counter
203 * \param os output stream
204 */
205 void PrintDec2BinNix(uint32_t decimalNum, uint32_t bitCount, std::ostream& os) const;
206};
207} // namespace ns3
208
209#endif /* NIX_VECTOR_H */
Neighbor-index data structure for nix-vector routing.
Definition: nix-vector.h:65
friend std::ostream & operator<<(std::ostream &os, const NixVector &nix)
Stream insertion operator.
Definition: nix-vector.cc:80
void AddNeighborIndex(uint32_t newBits, uint32_t numberOfBits)
Definition: nix-vector.cc:88
uint32_t m_used
For tracking where we are in the nix-vector.
Definition: nix-vector.h:189
uint32_t GetSerializedSize() const
Definition: nix-vector.cc:199
uint32_t m_epoch
Epoch of the Nix-vector creation.
Definition: nix-vector.h:197
uint32_t GetRemainingBits() const
Definition: nix-vector.cc:323
NixVector & operator=(const NixVector &o)
Definition: nix-vector.cc:55
uint32_t m_totalBitSize
A counter of how total bits are in the nix-vector.
Definition: nix-vector.h:195
uint32_t Serialize(uint32_t *buffer, uint32_t maxSize) const
Definition: nix-vector.cc:213
std::vector< uint32_t > NixBits_t
Typedef: the NixVector bits storage.
Definition: nix-vector.h:168
uint32_t ExtractNeighborIndex(uint32_t numberOfBits)
Definition: nix-vector.cc:144
NixBits_t m_nixVector
the actual nix-vector
Definition: nix-vector.h:188
void SetEpoch(uint32_t epoch)
Set the NixVector Epoch.
Definition: nix-vector.cc:381
void DumpNixVector(std::ostream &os) const
Print the NixVector.
Definition: nix-vector.cc:289
uint32_t Deserialize(const uint32_t *buffer, uint32_t size)
Definition: nix-vector.cc:239
Ptr< NixVector > Copy() const
Definition: nix-vector.cc:69
uint32_t BitCount(uint32_t numberOfNeighbors) const
Definition: nix-vector.cc:331
void PrintDec2BinNix(uint32_t decimalNum, uint32_t bitCount, std::ostream &os) const
Internal for pretty printing of nix-vector (no fill)
Definition: nix-vector.cc:354
uint32_t GetEpoch() const
Get the NixVector Epoch.
Definition: nix-vector.cc:387
Smart pointer class similar to boost::intrusive_ptr.
Definition: ptr.h:77
A template-based reference counting class.
Every class exported by the ns3 library is enclosed in the ns3 namespace.