source: rrlib_util/tTaggedPointer.h @ 68:34040d3abeb0

Last change on this file since 68:34040d3abeb0 was 68:34040d3abeb0, checked in by Max Reichardt <mreichardt@…>, 7 years ago

Tagged pointers can now have 32 bit tags on 32 bit platforms.

File size: 6.0 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. 19 bits is supported on all platforms (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 *                       Maximum bit width on 32 bit platforms is 32.
73 *
74 * Assertions make sure that only valid pointers and stamps are used.
75 */
76template <typename T, bool ALIGNED_POINTERS, uint TAG_BIT_WIDTH>
77class tTaggedPointer
78{
79  typedef tagged_pointer::tTaggedPointerImplementation<TAG_BIT_WIDTH, ALIGNED_POINTERS> tImplementation;
80
81  static_assert(TAG_BIT_WIDTH >= 1 && ((sizeof(void*) == 4 && TAG_BIT_WIDTH <= 32) || (TAG_BIT_WIDTH <= 16 || (ALIGNED_POINTERS && TAG_BIT_WIDTH <= 19))), "Invalid TAG_BIT_WIDTH");
82
83//----------------------------------------------------------------------
84// Public methods and typedefs
85//----------------------------------------------------------------------
86public:
87
88  /*! Integral type that pointer and tag are stored in */
89  typedef typename tImplementation::tStorage tStorage;
90
91  /*!
92   * Bit mask for tag.
93   * The bits in this constant may be used in tag.
94   */
95  enum { cSTAMP_MASK = (1 << TAG_BIT_WIDTH) - 1 };
96
97  tTaggedPointer() {}
98  tTaggedPointer(tStorage raw_tagged_pointer)
99  {
100    implementation.SetRaw(raw_tagged_pointer);
101  }
102  tTaggedPointer(T* pointer, uint stamp)
103  {
104    Set(pointer, stamp);
105  }
106
107  /*!
108   * \return Pointer stored in this object
109   */
110  T* GetPointer() const
111  {
112    return static_cast<T*>(implementation.GetPointer());
113  }
114
115  /*!
116   * \return Stamp stored in this object
117   */
118  uint GetStamp() const
119  {
120    return implementation.GetStamp();
121  }
122
123  /*!
124   * \param pointer New pointer
125   * \param stamp New stamp
126   */
127  void Set(T* pointer, uint stamp)
128  {
129    assert((stamp & cSTAMP_MASK) == stamp && "Stamp is out of bounds");
130    assert(((!ALIGNED_POINTERS) || ((((size_t)pointer) & 0x7) == 0)) && "Pointer is not aligned");
131    implementation.Set(pointer, stamp);
132  }
133
134  /*!
135   * \param pointer New pointer
136   */
137  void SetPointer(T* pointer)
138  {
139    assert(((!ALIGNED_POINTERS) || ((((size_t)pointer) & 0x7) == 0)) && "Pointer is not aligned");
140    implementation.SetPointer(pointer);
141  }
142
143  /*!
144   * \param stamp New stamp
145   */
146  void SetStamp(uint stamp)
147  {
148    assert((stamp & cSTAMP_MASK) == stamp && "Stamp is out of bounds");
149    implementation.SetStamp(stamp);
150  }
151
152  // operators
153
154  operator tStorage() const
155  {
156    return implementation.GetStorage();
157  }
158  operator tStorage&()
159  {
160    return implementation.GetStorageReference();
161  }
162
163  T& operator*() const
164  {
165    assert(GetPointer() && "Dereferencing null pointer is not allowed");
166    return *GetPointer();
167  }
168
169  T* operator->() const
170  {
171    assert(GetPointer() && "Dereferencing null pointer is not allowed");
172    return GetPointer();
173  }
174
175  tTaggedPointer& operator=(tStorage raw_tagged_pointer)
176  {
177    implementation.SetRaw(raw_tagged_pointer);
178    return *this;
179  }
180
181//----------------------------------------------------------------------
182// Private fields and methods
183//----------------------------------------------------------------------
184private:
185
186  /*! implementation */
187  tImplementation implementation;
188};
189
190//----------------------------------------------------------------------
191// End of namespace declaration
192//----------------------------------------------------------------------
193}
194}
195
196
197#endif
Note: See TracBrowser for help on using the repository browser.