This file is indexed.

/usr/include/ns3.26/ns3/object.h is in libns3-dev 3.26+dfsg-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2007 INRIA, Gustavo Carneiro
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Authors: Gustavo Carneiro <gjcarneiro@gmail.com>,
 *          Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
 */
#ifndef OBJECT_H
#define OBJECT_H

#include <stdint.h>
#include <string>
#include <vector>
#include "ptr.h"
#include "attribute.h"
#include "object-base.h"
#include "attribute-construction-list.h"
#include "simple-ref-count.h"

/**
 * \file
 * \ingroup object
 * ns3::Object class declaration, which is the root of the Object hierarchy
 * and Aggregation.
 */

namespace ns3 {

class Object;
class AttributeAccessor;
class AttributeValue;
class TraceSourceAccessor;

/**
 * \ingroup core
 * \defgroup object Object
 * \brief Base classes which provide memory management and object aggregation.
 */
  
/**
 * \ingroup object
 * \ingroup ptr
 * Standard Object deleter, used by SimpleRefCount
 * to delete an Object when the reference count drops to zero.
 */
struct ObjectDeleter
{
  /**
   * Smart pointer deleter implementation for Object.
   *
   * Delete implementation, forwards to the Object::DoDelete()
   * method.
   *
   * \param [in] object The Object to delete.
   */
  inline static void Delete (Object *object);
};

/**
 * \ingroup object
 * \brief A base class which provides memory management and object aggregation
 *
 * The memory management scheme is based on reference-counting with
 * dispose-like functionality to break the reference cycles.
 * The reference count is incremented and decremented with
 * the methods Ref() and Unref(). If a reference cycle is
 * present, the user is responsible for breaking it
 * by calling Dispose() in a single location. This will
 * eventually trigger the invocation of DoDispose() on itself and
 * all its aggregates. The DoDispose() method is always automatically
 * invoked from the Unref() method before destroying the Object,
 * even if the user did not call Dispose() directly.
 */
class Object : public SimpleRefCount<Object, ObjectBase, ObjectDeleter>
{
public:
  /**
   * \brief Register this type.
   * \return The Object TypeId.
   */
  static TypeId GetTypeId (void);

  /**
   * \brief Iterate over the Objects aggregated to an ns3::Object.
   *
   * This iterator does not allow you to iterate over the parent
   * Object used to call Object::GetAggregateIterator. 
   *
   * \note This is a java-style iterator.
   */
  class AggregateIterator
  {
public:
    /** Default constructor, which has no Object. */
    AggregateIterator ();

    /**
     * Check if there are more Aggregates to iterate over.
     *
     * \returns \c true if Next() can be called and return a non-null
     *          pointer, \c false otherwise.
     */
    bool HasNext (void) const;

    /**
     * Get the next Aggregated Object.
     *
     * \returns The next aggregated Object.
     */
    Ptr<const Object> Next (void);
private:
    friend class Object;
    /**
     * Construct from an Object.
     *
     * This is private, with Object as friend, so only Objects can create
     * useful AggregateIterators.
     *
     * \param [in] object The Object whose Aggregates should be iterated over.
     */
    AggregateIterator (Ptr<const Object> object);
    Ptr<const Object> m_object;                    //!< Parent Object.
    uint32_t m_current;                            //!< Current position in parent's aggegrates.
  };

  /** Constructor. */
  Object ();
  /** Destructor. */
  virtual ~Object ();

  /**
   * Implement the GetInstanceTypeId method defined in ObjectBase.
   */
  virtual TypeId GetInstanceTypeId (void) const;

  /**
   * Get a pointer to the requested aggregated Object.
   *
   * \returns A pointer to the requested Object, or zero
   *          if it could not be found.
   */
  template <typename T>
  inline Ptr<T> GetObject (void) const;
  /**
   * Get a pointer to the requested aggregated Object by TypeId.
   * 
   * \param [in] tid The TypeId of the requested Object.
   * \returns A pointer to the requested Object, or zero
   *          if it could not be found.
   */
  template <typename T>
  Ptr<T> GetObject (TypeId tid) const;
  /**
   * Dispose of this Object.
   *
   * Run the DoDispose() methods of this Object and all the
   * Objects aggregated to it.  
   * After calling this method, this Object is expected to be
   * totally unusable except for the Ref() and Unref() methods.
   *
   * \note You can call Dispose() many times on the same Object or
   * different Objects aggregated together, and DoDispose() will be
   * called only once for each aggregated Object.
   *
   * This method is typically used to break reference cycles.
   */
  void Dispose (void);
  /**
   * Aggregate two Objects together.
   *
   * \param [in] other The other Object pointer
   *
   * This method aggregates the two Objects together: after this
   * method returns, it becomes possible to call GetObject()
   * on one to get the other, and vice-versa. 
   *
   * This method calls the virtual method NotifyNewAggregates() to
   * notify all aggregated Objects that they have been aggregated
   * together.
   *
   * \sa NotifyNewAggregate()
   */
  void AggregateObject (Ptr<Object> other);

  /**
   * Get an iterator to the Objects aggregated to this one.
   *
   * \returns An iterator to the first Object aggregated to this
   *          Object.
   *
   * If no Objects are aggregated to this Object, then, the returned
   * iterator will be empty and AggregateIterator::HasNext() will
   * always return \c false.
   */
  AggregateIterator GetAggregateIterator (void) const;

  /**
   * Invoke DoInitialize on all Objects aggregated to this one.
   *
   * This method calls the virtual DoInitialize() method on all the Objects
   * aggregated to this Object. DoInitialize() will be called only once over
   * the lifetime of an Object, just like DoDispose() is called only
   * once.
   *
   * \sa DoInitialize()
   */
  void Initialize (void);

  /**
   * Check if the object has been initialized.
   *
   * \brief returns true if the object has been initialized. 
   */
  bool IsInitialized (void) const;

protected:
  /**
   * Notify all Objects aggregated to this one of a new Object being
   * aggregated.
   *
   * This method is invoked whenever two sets of Objects are aggregated
   * together.  It is invoked exactly once for each Object in both sets.
   * This method can be overriden by subclasses who wish to be notified
   * of aggregation events. These subclasses must chain up to their
   * base class NotifyNewAggregate() method.
   *
   * It is safe to call GetObject() and AggregateObject() from within
   * this method.
   */
  virtual void NotifyNewAggregate (void);
  /**
   * Initialize() implementation.
   *
   * This method is called only once by Initialize(). If the user
   * calls Initialize() multiple times, DoInitialize() is called only the
   * first time.
   *
   * Subclasses are expected to override this method and chain up
   * to their parent's implementation once they are done. It is
   * safe to call GetObject() and AggregateObject() from within this method.
   */
  virtual void DoInitialize (void);
  /**
   * Destructor implementation.
   *
   * This method is called by Dispose() or by the Object's 
   * destructor, whichever comes first.
   *
   * Subclasses are expected to implement their real destruction
   * code in an overriden version of this method and chain
   * up to their parent's implementation once they are done.
   * _i.e_, for simplicity, the destructor of every subclass should
   * be empty and its content should be moved to the associated
   * DoDispose() method.
   *
   * It is safe to call GetObject() from within this method.
   */
  virtual void DoDispose (void);
  /**
   * Copy an Object.
   *
   * \param [in] o the Object to copy.
   *
   * Allow subclasses to implement a copy constructor.
   *
   * While it is technically possible to implement a copy
   * constructor in a subclass, we strongly discourage you
   * from doing so. If you really want to do it anyway, you have
   * to understand that this copy constructor will _not_
   * copy aggregated Objects, _i.e_, if your Object instance
   * is already aggregated to another Object and if you invoke
   * this copy constructor, the new Object instance will be
   * a pristine standalone Object instance not aggregated to
   * any other Object. It is thus _your_ responsibility
   * as a caller of this method to do what needs to be done
   * (if it is needed) to ensure that the Object stays in a
   * valid state.
   */
  Object (const Object &o);
  
private:

  /**
   * Copy an Object.
   *
   * \param [in] object A pointer to the object to copy.
   * \returns A copy of the input object.
   *
   * This method invoke the copy constructor of the input object
   * and returns the new instance.
   */
  /**@{*/
  template <typename T>
  friend Ptr<T> CopyObject (Ptr<T> object);
  template <typename T>
  friend Ptr<T> CopyObject (Ptr<const T> object);
  /**@}*/
  
  /**
   * Set the TypeId and construct all Attributes of an Object.
   *
   * \tparam T \explicit The type of the derived object we are constructing.
   * \param [in] object The uninitialized object pointer.
   * \return The derived object.
   */
  template <typename T>
  friend Ptr<T> CompleteConstruct (T *object);

  friend class ObjectFactory;
  friend class AggregateIterator;
  friend struct ObjectDeleter;

  /**
   * The list of Objects aggregated to this one.
   *
   * This data structure uses a classic C-style trick to 
   * hold an array of variable size without performing
   * two memory allocations: the declaration of the structure
   * declares a one-element array but when we allocate
   * memory for this struct, we effectively allocate a larger
   * chunk of memory than the struct to allow space for a larger
   * variable sized buffer whose size is indicated by the element
   * \c n
   */
  struct Aggregates {
    /** The number of entries in \c buffer. */
    uint32_t n;
    /** The array of Objects. */
    Object *buffer[1];
  };

  /**
   * Find an Object of TypeId tid in the aggregates of this Object.
   *
   * \param [in] tid The TypeId we're looking for
   * \return The matching Object, if it is found
   */
  Ptr<Object> DoGetObject (TypeId tid) const;
  /**
   * Verify that this Object is still live, by checking it's reference count.
   * \return \c true if the reference count is non zero.
   */
  bool Check (void) const;
  /**
   * Check if any aggregated Objects have non-zero reference counts.
   *
   * \return \c true if any of our aggregates have non zero reference count.
   *
   * In some cases, when an event is scheduled against a subclass of
   * Object, and if no one owns a reference directly to this Object, the
   * Object is alive, has a refcount of zero and the method run when the
   * event expires runs against the raw pointer, which means that we are
   * manipulating an Object with a refcount of zero.  So, instead we
   * check the aggregate reference count.
   */
  bool CheckLoose (void) const;
  /**
   * Set the TypeId of this Object.
   
   * \param [in] tid The TypeId value to set.
   *
   * Invoked from ns3::CreateObject only.
   * Initialize the \c m_tid member variable to
   * keep track of the type of this Object instance.
   */
  void SetTypeId (TypeId tid);
  /**
   * Initialize all member variables registered as Attributes of this TypeId.
   *
   * \param [in] attributes The attribute values used to initialize
   *        the member variables of this Object's instance.
   *
   * Invoked from ns3::ObjectFactory::Create and ns3::CreateObject only.
   * Initialize all the member variables which were
   * registered with the associated TypeId.
  */
  void Construct (const AttributeConstructionList &attributes);

  /**
   * Keep the list of aggregates in most-recently-used order
   *
   * \param [in,out] aggregates The list of aggregated Objects.
   * \param [in] i The most recently used entry in the list.
   */
  void UpdateSortedArray (struct Aggregates *aggregates, uint32_t i) const;
  /**
   * Attempt to delete this Object.
   *
   * This method iterates over all aggregated Objects to check if they all 
   * have a zero refcount. If yes, the Object and all
   * its aggregates are deleted. If not, nothing is done.
   */
  void DoDelete (void);

  /**
   * Identifies the type of this Object instance.
   */
  TypeId m_tid;
  /**
   * Set to \c true when the DoDispose() method of the Object has run,
   * \c false otherwise.
   */
  bool m_disposed;
  /**
   * Set to \c true once the DoInitialize() method has run,
   * \c false otherwise
   */
  bool m_initialized;
  /**
   * A pointer to an array of 'aggregates'.
   *
   * A pointer to each Object aggregated to this Object is stored in this 
   * array.  The array is shared by all aggregated Objects
   * so the size of the array is indirectly a reference count.
   */
  struct Aggregates * m_aggregates;
  /**
   * The number of times the Object was accessed with a
   * call to GetObject().
   *
   * This integer is used to implement a heuristic to sort
   * the array of aggregates in most-frequently accessed order.
   */
  uint32_t m_getObjectCount;
};

template <typename T>
Ptr<T> CopyObject (Ptr<const T> object);
template <typename T>
Ptr<T> CopyObject (Ptr<T> object);

} // namespace ns3

namespace ns3 {


/*************************************************************************
 *   The Object implementation which depends on templates
 *************************************************************************/

void 
ObjectDeleter::Delete (Object *object)
{
  object->DoDelete ();
}

template <typename T>
Ptr<T> 
Object::GetObject () const
{
  // This is an optimization: if the cast works (which is likely),
  // things will be pretty fast.
  T *result = dynamic_cast<T *> (m_aggregates->buffer[0]);
  if (result != 0)
    {
      return Ptr<T> (result);
    }
  // if the cast does not work, we try to do a full type check.
  Ptr<Object> found = DoGetObject (T::GetTypeId ());
  if (found != 0)
    {
      return Ptr<T> (static_cast<T *> (PeekPointer (found)));
    }
  return 0;
}

template <typename T>
Ptr<T> 
Object::GetObject (TypeId tid) const
{
  Ptr<Object> found = DoGetObject (tid);
  if (found != 0)
    {
      return Ptr<T> (static_cast<T *> (PeekPointer (found)));
    }
  return 0;
}

/*************************************************************************
 *   The helper functions which need templates.
 *************************************************************************/

template <typename T>
Ptr<T> CopyObject (Ptr<T> object)
{
  Ptr<T> p = Ptr<T> (new T (*PeekPointer (object)), false);
  NS_ASSERT (p->GetInstanceTypeId () == object->GetInstanceTypeId ());
  return p;
}

template <typename T>
Ptr<T> CopyObject (Ptr<const T> object)
{
  Ptr<T> p = Ptr<T> (new T (*PeekPointer (object)), false);
  NS_ASSERT (p->GetInstanceTypeId () == object->GetInstanceTypeId ());
  return p;
}

template <typename T>
Ptr<T> CompleteConstruct (T *object)
{
  object->SetTypeId (T::GetTypeId ());
  object->Object::Construct (AttributeConstructionList ());
  return Ptr<T> (object, false);
}

/** 
 * \ingroup object
 * @{
 */
/**
 * Create an object by type, with varying number of constructor parameters.
 *
 * \tparam T \explicit The type of the derived object to construct.
 * \return The derived object.
 */
template <typename T>
Ptr<T> CreateObject (void)
{
  return CompleteConstruct (new T ());
}
/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the constructor argument.
 * \param [in] a1 The constructor argument
 * \return The derived object.
 */
template <typename T, typename T1>
Ptr<T> CreateObject (T1 a1)
{
  return CompleteConstruct (new T (a1));
}

/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the first constructor argument.
 * \tparam T2 \deduced The type of the second constructor argument.
 * \param [in] a1 The constructor first argument
 * \param [in] a2 The constructor second argument
 * \return The derived object.
 */
template <typename T, typename T1, typename T2>
Ptr<T> CreateObject (T1 a1, T2 a2)
{
  return CompleteConstruct (new T (a1,a2));
}

/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the first constructor argument.
 * \tparam T2 \deduced The type of the second constructor argument.
 * \tparam T3 \deduced The type of the third constructor argument.
 * \param [in] a1 The constructor first argument
 * \param [in] a2 The constructor second argument
 * \param [in] a3 The constructor third argument
 * \return The derived object.
 */
template <typename T, typename T1, typename T2, typename T3>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3)
{
  return CompleteConstruct (new T (a1,a2,a3));
}

/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the first constructor argument.
 * \tparam T2 \deduced The type of the second constructor argument.
 * \tparam T3 \deduced The type of the third constructor argument.
 * \tparam T4 \deduced The type of the fourth constructor argument.
 * \param [in] a1 The constructor first argument
 * \param [in] a2 The constructor second argument
 * \param [in] a3 The constructor third argument
 * \param [in] a4 The constructor fourth argument
 * \return The derived object.
 */
template <typename T, typename T1, typename T2, typename T3, typename T4>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4)
{
  return CompleteConstruct (new T (a1,a2,a3,a4));
}

/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the first constructor argument.
 * \tparam T2 \deduced The type of the second constructor argument.
 * \tparam T3 \deduced The type of the third constructor argument.
 * \tparam T4 \deduced The type of the fourth constructor argument.
 * \tparam T5 \deduced The type of the fifth constructor argument.
 * \param [in] a1 The constructor first argument
 * \param [in] a2 The constructor second argument
 * \param [in] a3 The constructor third argument
 * \param [in] a4 The constructor fourth argument
 * \param [in] a5 The constructor fifth argument
 * \return The derived object.
 */
template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5)
{
  return CompleteConstruct (new T (a1,a2,a3,a4,a5));
}

/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the first constructor argument.
 * \tparam T2 \deduced The type of the second constructor argument.
 * \tparam T3 \deduced The type of the third constructor argument.
 * \tparam T4 \deduced The type of the fourth constructor argument.
 * \tparam T5 \deduced The type of the fifth constructor argument.
 * \tparam T6 \deduced The type of the sixth constructor argument.
 * \param [in] a1 The constructor first argument
 * \param [in] a2 The constructor second argument
 * \param [in] a3 The constructor third argument
 * \param [in] a4 The constructor fourth argument
 * \param [in] a5 The constructor fifth argument
 * \param [in] a6 The constructor sixth argument
 * \return The derived object.
 */
template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6)
{
  return CompleteConstruct (new T (a1,a2,a3,a4,a5,a6));
}

/**
 * \copybrief CreateObject()
 * \tparam T \explicit The type of the derived object to construct.
 * \tparam T1 \deduced The type of the first constructor argument.
 * \tparam T2 \deduced The type of the second constructor argument.
 * \tparam T3 \deduced The type of the third constructor argument.
 * \tparam T4 \deduced The type of the fourth constructor argument.
 * \tparam T5 \deduced The type of the fifth constructor argument.
 * \tparam T6 \deduced The type of the sixth constructor argument.
 * \tparam T7 \deduced The type of the seventh constructor argument.
 * \param [in] a1 The constructor first argument
 * \param [in] a2 The constructor second argument
 * \param [in] a3 The constructor third argument
 * \param [in] a4 The constructor fourth argument
 * \param [in] a5 The constructor fifth argument
 * \param [in] a6 The constructor sixth argument
 * \param [in] a7 The constructor seventh argument
 * \return The derived object.
 */
template <typename T, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7>
Ptr<T> CreateObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6, T7 a7)
{
  return CompleteConstruct (new T (a1,a2,a3,a4,a5,a6,a7));
}
/**@}*/

} // namespace ns3

#endif /* OBJECT_H */