sharedheap.h 10.6 KB
Newer Older
1
2
3
4
5
/*! \file sharedheap.h
 * \brief shared heap representation (prototypes)
 * 
 * ----------------------------------------------------------------------------
 * 
6
 * $Id$
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
 * \author Thomas Forbriger
 * \since 08/12/2002
 * 
 * shared heap representation (prototypes)
 *
 * ----
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version. 
 * 
 * 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 * ----
 *
 * \sa aff::SHeap
 * \sa aff::ConstSharedHeap
 * \sa aff::SharedHeap
 * 
 * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) 
 * 
 * REVISIONS and CHANGES 
 *  - 08/12/2002   V1.0   copied from libcontxx
 *  - 16/12/2002   V1.1   (thof)
 *                        - introduced new concept of const correct containers
 *                        - moved AllocException to error.h
 *  - 17/12/2002   V1.2   (thof)
 *                        - use access declarations (hint by wolle)
 *  - 20/12/2002   V1.3   (thof)
 *                        - moved SHeap to namespace util
 *  - 28/12/2002   V1.4   (thof)
 *                        - changed base class from specialization to
 *                          independent class template
 *                        - added class documentation
 *  - 29/12/2002   V1.5   (thof)
 *                        - use "using" syntax for access declarations
 *                        - resolved conflicts with protected operator[]
 *                          in derived classes
 *  - 31/12/2002   V1.6   (thof)
 *                        - removed constructor from Theadstruct
 *                        - made the non-initializing constructor
 *                          protected. Default constructor remains public (it
 *                          is needed if we construct a container for
 *                          ConstSharedHeap elements).
 *  - 19/12/2003   V1.7   (thof)
 *                        - index check now should work
 *  - 04/07/2005   V1.8   (thof)
 *                        - allows data modification through instances being
 *                          declared const
 * 
 * ============================================================================
 */

// include guard
#ifndef AFF_SHAREDHEAP_H_VERSION

#define AFF_SHAREDHEAP_H_VERSION \
  "AFF_SHAREDHEAP_H   V1.8"
#define AFF_SHAREDHEAP_H_CVSID \
72
  "$Id$"
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

#include<new>
#include<aff/lib/error.h>
#include<aff/lib/types.h>

namespace aff {

#ifdef AFF_PREBUILT
namespace prebuilt {
#endif

  /*----------------------------------------------------------------------*/

namespace util {

  /*! \brief A structure to be shared between different SharedHeap instances.
   *
   * This is the core part of represented shared heap. Only objects of this
   * class allocate and delete memory. The SharedHeap representation has holds
   * a pointer to an instance of this struct. The representation is
   * responsible for doing the reference counting by incrementing and
   * decrementing Mnref and to call the destructor of SHeap once the reference
   * count drops to zero. The actual deallocation of the memory block used for
   * the array is, however, done within the destructor of SHeap. 
   *
   * For arrays taken from Fortran code we use a flag \c Mextern. If it is
   * true, this indicates that memory should neither be allocated be the
   * constructor nor given free by the destructor.
   *
   * \sa aff::SharedHeap
   */
  template<typename T>
    struct SHeap
    {
      //! Allocate memory on heap.
      SHeap(const Tsize& size);
      //! Take memory reference from elsewhere
      SHeap(T* pointer, const Tsize& size);

      //! Free heap memory.
      ~SHeap();

      T*     Mheap;   //!< shared raw array on heap
      Tsize  Msize;   //!< size (number of elements) of array
      Tsize  Mnref;   //!< number of referencing instances
      bool   Mextern; //!< true if memory allocation is handled elsewhere
    }; // struct SHeap

} // namespace util

  /*======================================================================*/

  /*! \brief This is the base class for const elements
   *
   * This is the base class for aff::SharedHeap. Although it accesses the data
   * in memory through a pointer of type \c T*, it does not allow
   * modification of the data through public access. Only for derived classes
   * protected members are provided that allow modification of the data.
   *
   * The whole functionality of shared heap (see "\ref page_representation")
   * is implemented within this base class. aff::SharedHeap is only a sparse
   * wrapper.
   *
   * \sa aff::SharedHeap
   * \sa aff::SHeap
   * \sa \ref sec_design_const
   * \sa \ref page_representation
   */
  template <class T>
    class ConstSharedHeap
    {
      public:
        //! Element type
        typedef const T Tvalue;
        //! Type of pointer to element
        typedef const T* Tpointer;
        //! Type of reference to element
        typedef const T& Treference;
        //! this class
        typedef aff::ConstSharedHeap<T> Tcontainer;
        //! Type of const version of SharedHeap
        typedef aff::ConstSharedHeap<T> Tcontainer_of_const;
        //! short for container of const
        typedef aff::ConstSharedHeap<T> Tcoc;

      private:
        //! Type of SHeap struct to be used in any case
        typedef aff::util::SHeap<T> Theapstruct;

      public:
        //! Create from nothing.
        ConstSharedHeap();

        //! Create representation for externally managed memory
        ConstSharedHeap(T* pointer, const Tsize& size);

        //! Copy representation to share heap.
        ConstSharedHeap(const Tcontainer& sharedheap);

        //! Deallocate heap memory if this is the last referencing instance.
        ~ConstSharedHeap();

        //! Copy representation to share heap.
        ConstSharedHeap<T>& operator=(const Tcontainer& sharedheap);

        /*! Return size (always inline).
         * \retval size of array on heap.
         */
        inline
        const Tsize& size() const
        { return(Mheapstruct->Msize); }

        /*! Return array access.
         * \return pointer to array on heap
         */
        const T* array() const
        { return(Mheapstruct->Mheap); }

        //! Index operator (always inline).
        inline
        const T& operator[](const Tsubscript& i) const
        { 
#ifdef AFF_INDEXCHECK
          AFF_assert(((i<Tsubscript(Mheapstruct->Msize)) && (i>=0)),
                     "SharedHeap: illegal index position!");
#endif
          return(Mheapstruct->Mheap[i]); 
        }

      /*-----------------------------------------------------------------*/
      /* here starts the PROTECTED section!
       * ----------------------------------
       *
       * These functions are needed by the derived aff::SharedHeap class to
       * access its base class and the data elements contained therein in a
       * defined way.
       */
      protected:
        //! Allocate new heap memory.
        ConstSharedHeap(const Tsize& size);

        //! write access to data
        inline
        T& write_access(const Tsubscript& i) const
        { 
#ifdef AFF_INDEXCHECK
          AFF_assert(((i<Tsubscript(Mheapstruct->Msize)) && (i>=0)),
                     "SharedHeap: illegal index position!");
#endif
          return(Mheapstruct->Mheap[i]); 
        }

        /*! Return array access.
         * \return pointer to array on heap
         */
        T* writable_array()
        { return(Mheapstruct->Mheap); }

      private:
        Theapstruct* Mheapstruct; //!< shared heap structure

    }; // class ConstSharedHeap<T>

  /*======================================================================*/

  /*! \brief A template class to share heap memory for different array
   * projections.
   *
   * This is a wrapper class that inherits publicly from aff::ConstSharedHeap.
   * Thus containers of type aff::SharedHeap and aff::ConstSharedHeap may
   * share the reference to memory through which they access the data. And the
   * conversion to the base class that does not allow modification of elements
   * is a trivial conversion.
   *
   * This class essentially adds no functionality. It just provides public
   * access to the protected members of aff::ConstSharedHeap. For further
   * documentation see there.
   *
   * \sa \ref page_representation
   * \sa aff::ConstSharedHeap
   */
  template <class T>
    class SharedHeap: public aff::ConstSharedHeap<T>
    {
      public:
        //! Element type
        typedef T Tvalue;
        //! Type of pointer to element
        typedef T* Tpointer;
        //! Type of reference to element
        typedef T& Treference;
        //! this class
        typedef aff::SharedHeap<T> Tcontainer;
        //! base class
        typedef aff::ConstSharedHeap<T> Tbase;
        //! Type of const version of SharedHeap
        typedef Tbase Tcontainer_of_const;
        //! short for container of const
        typedef Tbase Tcoc;

      public:
        //! Create from nothing.
        SharedHeap(): Tbase() { }

        //! Allocate new heap memory.
        SharedHeap(const Tsize& size): Tbase(size) { }

        //! Create representation for externally managed memory
        SharedHeap(T* pointer, const Tsize& size):
          Tbase(pointer, size) { }

        //! Copy representation to share heap.
        SharedHeap(const Tcontainer& sharedheap):
          Tbase(sharedheap) { }

        //! Deallocate heap memory if this is the last referencing instance.
        ~SharedHeap() { }

        //! \name access declarations
        //@{
        //! access to base class function
        using Tbase::size;
        using Tbase::operator[];
        using Tbase::array;
        //@}

        //! delegate to base
        T& operator[](const Tsubscript& i) const
        { return(this->Tbase::write_access(i)); }

        /*! Return array access.
         * \return pointer to array on heap
         */
        T* array() const
        { return(this->Tbase::writable_array()); }
        
    }; // class SharedHeap

#ifdef AFF_PREBUILT
} // namespace prebuilt
#endif

} // namespace aff

#ifndef AFF_NO_DEFINITIONS
#include <aff/lib/sharedheap_def.h>
#endif

#endif // AFF_SHAREDHEAP_H_VERSION (includeguard)

/* ----- END OF sharedheap.h ----- */