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