source: rrlib_util/tTaggedPointer.h @ 67:e2bb58a307d2

Last change on this file since 67:e2bb58a307d2 was 67:e2bb58a307d2, checked in by Max Reichardt <mreichardt@…>, 8 years ago

Small improvements to tTaggedPointer:

  • Added constructor
  • Added a non-const conversion operator returning reference for use in atomics
  • Introduced common base class for tTaggedPointerImplementation
File size: 5.9 KB
Line 
1//
2// You received this file as part of RRLib
3// Robotics Research Library
4//
5// Copyright (C) Finroc GbR (finroc.org)
6//
7// This program is free software; you can redistribute it and/or
8// modify it under the terms of the GNU General Public License
9// as published by the Free Software Foundation; either version 2
10// of the License, or (at your option) any later version.
11//
12// This program is distributed in the hope that it will be useful,
13// but WITHOUT ANY WARRANTY; without even the implied warranty of
14// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15// GNU General Public License for more details.
16//
17// You should have received a copy of the GNU General Public License
18// along with this program; if not, write to the Free Software
19// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
20//
21//----------------------------------------------------------------------
22/*!\file    rrlib/util/tTaggedPointer.h
23 *
24 * \author  Max Reichardt
25 *
26 * \date    2012-10-09
27 *
28 * \brief   Contains tTaggedPointer
29 *
30 * \b tTaggedPointer
31 *
32 * Tagged pointer class.
33 * This class is used to store a pointer together with an integer in a value of integral type.
34 */
35//----------------------------------------------------------------------
36#ifndef __rrlib__util__tTaggedPointer_h__
37#define __rrlib__util__tTaggedPointer_h__
38
39//----------------------------------------------------------------------
40// External includes (system with <>, local with "")
41//----------------------------------------------------------------------
42
43//----------------------------------------------------------------------
44// Internal includes with ""
45//----------------------------------------------------------------------
46#include "rrlib/util/tagged_pointer/tTaggedPointerImplementation.h"
47
48//----------------------------------------------------------------------
49// Namespace declaration
50//----------------------------------------------------------------------
51namespace rrlib
52{
53namespace util
54{
55
56//----------------------------------------------------------------------
57// Forward declarations / typedefs / enums
58//----------------------------------------------------------------------
59
60//----------------------------------------------------------------------
61// Class declaration
62//----------------------------------------------------------------------
63//! Tagged pointer class
64/*!
65 * This class is used to store a pointer together with a 'tag' (integer) in a value of integral type (tStorage).
66 *
67 * \tparam Pointer type (without *)
68 * \tparam ALIGNED_POINTERS Are the T pointers used with this class 8-byte aligned? (Typically the case for any object T created with 'new')
69 * \tparam TAG_BIT_WIDTH Bit width of tag. For maximum portability, this is limited to 19 bits (values 0-524287) for aligned pointers
70 *                       and 16 bits (values 0-65535) for non-aligned pointers.
71 *                       A value of <= 3 (values 0-7) requires only a 32 bit integer for aligned pointers on 32 bit platforms.
72 *
73 * Assertions make sure that only valid pointers and stamps are used.
74 */
75template <typename T, bool ALIGNED_POINTERS, uint TAG_BIT_WIDTH>
76class tTaggedPointer
77{
78  typedef tagged_pointer::tTaggedPointerImplementation<TAG_BIT_WIDTH, ALIGNED_POINTERS> tImplementation;
79
80  static_assert(TAG_BIT_WIDTH >= 1 && (TAG_BIT_WIDTH <= 16 || (ALIGNED_POINTERS && TAG_BIT_WIDTH <= 19)), "Invalid TAG_BIT_WIDTH");
81
82//----------------------------------------------------------------------
83// Public methods and typedefs
84//----------------------------------------------------------------------
85public:
86
87  /*! Integral type that pointer and tag are stored in */
88  typedef typename tImplementation::tStorage tStorage;
89
90  /*!
91   * Bit mask for tag.
92   * The bits in this constant may be used in tag.
93   */
94  enum { cSTAMP_MASK = (1 << TAG_BIT_WIDTH) - 1 };
95
96  tTaggedPointer() {}
97  tTaggedPointer(tStorage raw_tagged_pointer)
98  {
99    implementation.SetRaw(raw_tagged_pointer);
100  }
101  tTaggedPointer(T* pointer, int stamp)
102  {
103    Set(pointer, stamp);
104  }
105
106  /*!
107   * \return Pointer stored in this object
108   */
109  T* GetPointer() const
110  {
111    return static_cast<T*>(implementation.GetPointer());
112  }
113
114  /*!
115   * \return Stamp stored in this object
116   */
117  int GetStamp() const
118  {
119    return implementation.GetStamp();
120  }
121
122  /*!
123   * \param pointer New pointer
124   * \param stamp New stamp
125   */
126  void Set(T* pointer, int stamp)
127  {
128    assert((stamp & cSTAMP_MASK) == stamp && "Stamp is out of bounds");
129    assert(((!ALIGNED_POINTERS) || ((((size_t)pointer) & 0x7) == 0)) && "Pointer is not aligned");
130    implementation.Set(pointer, stamp);
131  }
132
133  /*!
134   * \param pointer New pointer
135   */
136  void SetPointer(T* pointer)
137  {
138    assert(((!ALIGNED_POINTERS) || ((((size_t)pointer) & 0x7) == 0)) && "Pointer is not aligned");
139    implementation.SetPointer(pointer);
140  }
141
142  /*!
143   * \param stamp New stamp
144   */
145  void SetStamp(int stamp)
146  {
147    assert((stamp & cSTAMP_MASK) == stamp && "Stamp is out of bounds");
148    implementation.SetStamp(stamp);
149  }
150
151  // operators
152
153  operator tStorage() const
154  {
155    return implementation.GetStorage();
156  }
157  operator tStorage&()
158  {
159    return implementation.GetStorageReference();
160  }
161
162  T& operator*() const
163  {
164    assert(GetPointer() && "Dereferencing null pointer is not allowed");
165    return *GetPointer();
166  }
167
168  T* operator->() const
169  {
170    assert(GetPointer() && "Dereferencing null pointer is not allowed");
171    return GetPointer();
172  }
173
174  tTaggedPointer& operator=(tStorage raw_tagged_pointer)
175  {
176    implementation.SetRaw(raw_tagged_pointer);
177    return *this;
178  }
179
180//----------------------------------------------------------------------
181// Private fields and methods
182//----------------------------------------------------------------------
183private:
184
185  /*! implementation */
186  tImplementation implementation;
187};
188
189//----------------------------------------------------------------------
190// End of namespace declaration
191//----------------------------------------------------------------------
192}
193}
194
195
196#endif
Note: See TracBrowser for help on using the repository browser.