A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
object-base.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef OBJECT_BASE_H
9#define OBJECT_BASE_H
10
11#include "callback.h"
12#include "type-id.h"
13#include "warnings.h"
14
15#include <list>
16#include <string>
17
18/**
19 * \file
20 * \ingroup object
21 * ns3::ObjectBase declaration and
22 * NS_OBJECT_ENSURE_REGISTERED() macro definition.
23 */
24
25/**
26 * \ingroup object
27 * \brief Register an Object subclass with the TypeId system.
28 *
29 * This macro should be invoked once for every class which
30 * defines a new GetTypeId method.
31 *
32 * If the class is in a namespace, then the macro call should also be
33 * in the namespace.
34 */
35#define NS_OBJECT_ENSURE_REGISTERED(type) \
36 static struct Object##type##RegistrationClass \
37 { \
38 Object##type##RegistrationClass() \
39 { \
40 NS_WARNING_PUSH_DEPRECATED; \
41 ns3::TypeId tid = type::GetTypeId(); \
42 tid.SetSize(sizeof(type)); \
43 tid.GetParent(); \
44 NS_WARNING_POP; \
45 } \
46 } Object##type##RegistrationVariable
47
48/**
49 * \ingroup object
50 * \brief Explicitly instantiate a template class with one template parameter
51 * and register the resulting instance with the TypeId system.
52 *
53 * This macro should be invoked once for every required instance of a template
54 * class with one template parameter which derives from the Object class and
55 * defines a new GetTypeId method.
56 *
57 * If the template class is in a namespace, then the macro call should also be
58 * in the namespace.
59 *
60 * \note The type names used as arguments for this macro, being used to form a
61 * class name and a variable name, CANNOT contain the scope resolution
62 * operator (::)
63 *
64 * \tparam type the template class
65 * \tparam param the first template parameter
66 */
67#define NS_OBJECT_TEMPLATE_CLASS_DEFINE(type, param) \
68 template class type<param>; \
69 template <> \
70 std::string DoGetTemplateClassName<type<param>>() \
71 { \
72 return std::string("ns3::") + std::string(#type) + std::string("<") + \
73 std::string(#param) + std::string(">"); \
74 } \
75 static struct Object##type##param##RegistrationClass \
76 { \
77 Object##type##param##RegistrationClass() \
78 { \
79 ns3::TypeId tid = type<param>::GetTypeId(); \
80 tid.SetSize(sizeof(type<param>)); \
81 tid.GetParent(); \
82 } \
83 } Object##type##param##RegistrationVariable
84
85/**
86 * \ingroup object
87 * \brief Explicitly instantiate a template class with two template parameters
88 * and register the resulting instance with the TypeId system.
89 *
90 * This macro should be invoked once for every required instance of a template
91 * class with two template parameters which derives from the Object class and
92 * defines a new GetTypeId method.
93 *
94 * If the template class is in a namespace, then the macro call should also be
95 * in the namespace.
96 *
97 * \note The type names used as arguments for this macro, being used to form a
98 * class name and a variable name, CANNOT contain the scope resolution
99 * operator (::)
100 *
101 * \tparam type the template class
102 * \tparam param1 the first template parameter
103 * \tparam param2 the second template parameter
104 */
105#define NS_OBJECT_TEMPLATE_CLASS_TWO_DEFINE(type, param1, param2) \
106 template class type<param1, param2>; \
107 template <> \
108 std::string DoGetTemplateClassName<type<param1, param2>>() \
109 { \
110 return std::string("ns3::") + std::string(#type) + std::string("<") + \
111 std::string(#param1) + std::string(",") + std::string(#param2) + std::string(">"); \
112 } \
113 static struct Object##type##param1##param2##RegistrationClass \
114 { \
115 Object##type##param1##param2##RegistrationClass() \
116 { \
117 ns3::TypeId tid = type<param1, param2>::GetTypeId(); \
118 tid.SetSize(sizeof(type<param1, param2>)); \
119 tid.GetParent(); \
120 } \
121 } Object##type##param1##param2##RegistrationVariable
122
123namespace ns3
124{
125
126/**
127 * \brief Helper function to get the name (as a string) of the type
128 * of a template class
129 * \return the name of the type of a template class as a string
130 *
131 * A specialization of this function is defined by the
132 * NS_OBJECT_TEMPLATE_CLASS_DEFINE macro.
133 */
134template <typename T>
136
137/**
138 * \brief Helper function to get the name (as a string) of the type
139 * of a template class
140 * \return the name of the type of a template class as a string
141 */
142template <typename T>
143std::string
148
149class AttributeConstructionList;
150
151/**
152 * \ingroup object
153 *
154 * \brief Anchor the ns-3 type and attribute system.
155 *
156 * Every class which wants to integrate in the ns-3 type and attribute
157 * system should derive from this base class. This base class provides:
158 * - A way to associate an ns3::TypeId to each object instance.
159 * - A way to set and get the attributes registered in the ns3::TypeId.
160 */
162{
163 public:
164 /**
165 * Get the type ID.
166 * \return The object TypeId.
167 */
168 static TypeId GetTypeId();
169
170 /**
171 * Virtual destructor.
172 */
173 virtual ~ObjectBase();
174
175 /**
176 * Get the most derived TypeId for this Object.
177 *
178 * This method is typically implemented by ns3::Object::GetInstanceTypeId
179 * but some classes which derive from ns3::ObjectBase directly
180 * have to implement it themselves.
181 *
182 * \return The TypeId associated to the most-derived type
183 * of this instance.
184 */
185 virtual TypeId GetInstanceTypeId() const = 0;
186
187 /**
188 *
189 * Set a single attribute, raising fatal errors if unsuccessful.
190 *
191 * This will either succeed at setting the attribute
192 * or it will raise NS_FATAL_ERROR() on these conditions:
193 *
194 * - The attribute doesn't exist in this Object.
195 * - The attribute can't be set (no Setter).
196 * - The attribute couldn't be deserialized from the AttributeValue.
197 *
198 * \param [in] name The name of the attribute to set.
199 * \param [in] value The name of the attribute to set.
200 */
201 void SetAttribute(std::string name, const AttributeValue& value);
202 /**
203 * Set a single attribute without raising errors.
204 *
205 * If the attribute could not be set this will return \c false,
206 * but not raise any errors.
207 *
208 * \param [in] name The name of the attribute to set.
209 * \param [in] value The value to set it to.
210 * \return \c true if the requested attribute exists and could be set,
211 * \c false otherwise.
212 */
213 bool SetAttributeFailSafe(std::string name, const AttributeValue& value);
214 /**
215 * Get the value of an attribute, raising fatal errors if unsuccessful.
216 *
217 * This will either succeed at setting the attribute
218 * or it will raise NS_FATAL_ERROR() on these conditions:
219 *
220 * - The attribute doesn't exist in this Object.
221 * - The attribute can't be read (no Getter).
222 * - The attribute doesn't support string formatting.
223 * - The attribute couldn't be serialized into the AttributeValue.
224 *
225 * \param [in] name The name of the attribute to read.
226 * \param [out] value Where the result should be stored.
227 * \param [in] permissive If false (by default), will generate warnings and errors for
228 * deprecated and obsolete attributes, respectively. If set to true, warnings for deprecated
229 * attributes will be suppressed.
230 */
231 void GetAttribute(std::string name, AttributeValue& value, bool permissive = false) const;
232 /**
233 * Get the value of an attribute without raising errors.
234 *
235 * If the attribute could not be read this will return \c false,
236 * but not raise any errors.
237 *
238 * \param [in] name The name of the attribute to read.
239 * \param [out] value Where the result value should be stored.
240 * \return \c true if the requested attribute was found, \c false otherwise.
241 */
242 bool GetAttributeFailSafe(std::string name, AttributeValue& value) const;
243
244 /**
245 * Connect a TraceSource to a Callback with a context.
246 *
247 * The target trace source should be registered with TypeId::AddTraceSource.
248 *
249 * \param [in] name The name of the target trace source.
250 * \param [in] context The trace context associated to the callback.
251 * \param [in] cb The callback to connect to the trace source.
252 * \returns \c true on success, \c false if TraceSource was not found.
253 */
254 bool TraceConnect(std::string name, std::string context, const CallbackBase& cb);
255 /**
256 * Connect a TraceSource to a Callback without a context.
257 *
258 * The target trace source should be registered with TypeId::AddTraceSource.
259 *
260 * \param [in] name The name of the target trace source.
261 * \param [in] cb The callback to connect to the trace source.
262 * \returns \c true on success, \c false if TraceSource was not found.
263 */
264 bool TraceConnectWithoutContext(std::string name, const CallbackBase& cb);
265 /**
266 * Disconnect from a TraceSource a Callback previously connected
267 * with a context.
268 *
269 * The target trace source should be registered with TypeId::AddTraceSource.
270 *
271 * \param [in] name The name of the target trace source.
272 * \param [in] context The trace context associated to the callback.
273 * \param [in] cb The callback to disconnect from the trace source.
274 * \returns \c true on success, \c false if TraceSource was not found.
275 */
276 bool TraceDisconnect(std::string name, std::string context, const CallbackBase& cb);
277 /**
278 * Disconnect from a TraceSource a Callback previously connected
279 * without a context.
280 *
281 * The target trace source should be registered with TypeId::AddTraceSource.
282 *
283 * \param [in] name The name of the target trace source.
284 * \param [in] cb The callback to disconnect from the trace source.
285 * \returns \c true on success, \c false if TraceSource was not found.
286 */
287 bool TraceDisconnectWithoutContext(std::string name, const CallbackBase& cb);
288
289 protected:
290 /**
291 * Notifier called once the ObjectBase is fully constructed.
292 *
293 * This method is invoked once all member attributes have been
294 * initialized. Subclasses can override this method to be notified
295 * of this event but if they do this, they must chain up to their
296 * parent's NotifyConstructionCompleted method.
297 */
298 virtual void NotifyConstructionCompleted();
299 /**
300 * Complete construction of ObjectBase; invoked by derived classes.
301 *
302 * Invoked from subclasses to initialize all of their
303 * attribute members. This method will typically be invoked
304 * automatically from ns3::CreateObject if your class derives
305 * from ns3::Object. If you derive from ns3::ObjectBase directly,
306 * you should make sure that you invoke this method from
307 * your most-derived constructor.
308 *
309 * \param [in] attributes The attribute values used to initialize
310 * the member variables of this object's instance.
311 */
312 void ConstructSelf(const AttributeConstructionList& attributes);
313
314 private:
315 /**
316 * Attempt to set the value referenced by the accessor \pname{spec}
317 * to a valid value according to the \c checker, based on \pname{value}.
318 *
319 * \param [in] spec The accessor for the storage location.
320 * \param [in] checker The checker to use in validating the value.
321 * \param [in] value The value to attempt to store.
322 * \returns \c true if the \c value could be validated by the \pname{checker}
323 * and written to the storage location.
324 */
327 const AttributeValue& value);
328};
329
330// The following explicit template instantiation declarations prevent all the translation
331// units including this header file to implicitly instantiate the callbacks class and
332// function templates having ObjectBase as template type parameter that are required to be
333// instantiated more often (accorging to the ClangBuildAnalyzer tool).
334// These classes and functions are explicitly instantiated in object-base.cc
336extern template Callback<ObjectBase*>::Callback();
337extern template class CallbackImpl<ObjectBase*>;
338
339} // namespace ns3
340
341#endif /* OBJECT_BASE_H */
Declaration of the various callback functions.
List of Attribute name, value and checker triples used to construct Objects.
Hold a value for an Attribute.
Definition attribute.h:59
Base class for Callback class.
Definition callback.h:344
Callback template class.
Definition callback.h:422
friend class Callback
Definition callback.h:424
CallbackImpl class with varying numbers of argument types.
Definition callback.h:226
Anchor the ns-3 type and attribute system.
bool TraceConnectWithoutContext(std::string name, const CallbackBase &cb)
Connect a TraceSource to a Callback without a context.
bool TraceDisconnect(std::string name, std::string context, const CallbackBase &cb)
Disconnect from a TraceSource a Callback previously connected with a context.
bool TraceDisconnectWithoutContext(std::string name, const CallbackBase &cb)
Disconnect from a TraceSource a Callback previously connected without a context.
virtual TypeId GetInstanceTypeId() const =0
Get the most derived TypeId for this Object.
void ConstructSelf(const AttributeConstructionList &attributes)
Complete construction of ObjectBase; invoked by derived classes.
virtual ~ObjectBase()
Virtual destructor.
bool GetAttributeFailSafe(std::string name, AttributeValue &value) const
Get the value of an attribute without raising errors.
virtual void NotifyConstructionCompleted()
Notifier called once the ObjectBase is fully constructed.
static TypeId GetTypeId()
Get the type ID.
bool SetAttributeFailSafe(std::string name, const AttributeValue &value)
Set a single attribute without raising errors.
void SetAttribute(std::string name, const AttributeValue &value)
Set a single attribute, raising fatal errors if unsuccessful.
bool TraceConnect(std::string name, std::string context, const CallbackBase &cb)
Connect a TraceSource to a Callback with a context.
void GetAttribute(std::string name, AttributeValue &value, bool permissive=false) const
Get the value of an attribute, raising fatal errors if unsuccessful.
bool DoSet(Ptr< const AttributeAccessor > spec, Ptr< const AttributeChecker > checker, const AttributeValue &value)
Attempt to set the value referenced by the accessor spec to a valid value according to the checker,...
Smart pointer class similar to boost::intrusive_ptr.
a unique identifier for an interface.
Definition type-id.h:48
template Callback< ObjectBase * > MakeCallback< ObjectBase * >(ObjectBase *(*)())
Explicit instantiation for ObjectBase.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::string DoGetTemplateClassName()
Helper function to get the name (as a string) of the type of a template class.
std::string GetTemplateClassName()
Helper function to get the name (as a string) of the type of a template class.
ns3::TypeId declaration; inline and template implementations.