sharedheap.h 7.18 KB
Newer Older
1
2
3
4
5
/*! \file sharedheap.h
 * \brief shared heap representation (prototypes)
 * 
 * ----------------------------------------------------------------------------
 * 
thomas.forbriger's avatar
thomas.forbriger committed
6
 * $Id: sharedheap.h,v 1.8 2002-12-16 18:02:01 forbrig Exp $
7
 * \author Thomas Forbriger
8
 * \since 08/12/2002
9
10
 * 
 * shared heap representation (prototypes)
11
 * \sa aff::SharedHeap
12
13
 * \sa aff::SHeap
 * \sa aff::AllocException
14
15
16
17
 * 
 * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) 
 * 
 * REVISIONS and CHANGES 
18
 *  - 08/12/2002   V1.0   copied from libcontxx
19
20
21
22
23
 * 
 * ============================================================================
 */

// include guard
24
#ifndef AFF_SHAREDHEAP_H_VERSION
25

26
27
28
#define AFF_SHAREDHEAP_H_VERSION \
  "AFF_SHAREDHEAP_H   V1.2   "
#define AFF_SHAREDHEAP_H_CVSID \
thomas.forbriger's avatar
thomas.forbriger committed
29
  "$Id: sharedheap.h,v 1.8 2002-12-16 18:02:01 forbrig Exp $"
30
31

#include<new>
thomas.forbriger's avatar
thomas.forbriger committed
32
#include<aff/lib/error.h>
33
34
#include<aff/lib/types.h>
#include<aff/lib/qualified.h>
35

36
namespace aff {
37

38
#ifdef AFF_PREBUILT
39
40
41
namespace prebuilt {
#endif

thomas.forbriger's avatar
thomas.forbriger committed
42
43
44
45
46
#ifdef AFF_PREBUILT
  using namespace aff::prebuilt::util;
#else
  using namespace aff::util;
#endif
47

48
49
  /*! \brief Exception thrown in case of allocation error
   *
thomas.forbriger's avatar
thomas.forbriger committed
50
   * \ingroup group_error
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
   * \sa aff::Exception
   */
  class AllocException:
    public Exception
  {
    public:
      //! take number of requested elements and their size
      AllocException(const Tsize& n, const Tsize& size);
      //! Screen report
      virtual void report() const;
    private:
      //! members to remember
      Tsize Mn, Msize;
  }; // class AllocException

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

thomas.forbriger's avatar
thomas.forbriger committed
68
  /*! \brief A structure to be shared between different SharedHeap instances.
69
70
71
72
73
74
75
76
77
78
79
80
   *
   * 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.
thomas.forbriger's avatar
thomas.forbriger committed
81
82
   *
   * \sa aff::SharedHeap
83
84
85
86
87
88
89
90
   */
  template<typename T>
    struct SHeap
    {
      //! Allocate memory on heap.
      SHeap(const Tsize& size);
      //! Take memory reference from elsewhere
      SHeap(T* pointer, const Tsize& size);
91

92
93
      //! Free heap memory.
      ~SHeap();
94

95
96
97
98
99
100
101
      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

  /*----------------------------------------------------------------------*/
102
103
104
105
106

  /*! \brief A template class to share heap memory for different array
   * projections.
   *
   * \sa \ref page_representation
107
108
109
110
   *
   * \todo 
   * Add usefull documentation to this class.
   *
thomas.forbriger's avatar
thomas.forbriger committed
111
   * \sa aff::SHeap
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
   */
  template <typename T>
    class SharedHeap
    {
      public:
        //! Element type
        typedef typename Qualified<T>::Tvalue Tvalue;
        //! Type of pointer to element
        typedef typename Qualified<T>::Tpointer Tpointer;
        //! Type of reference to element
        typedef typename Qualified<T>::Treference Treference;
        //! Type of const reference to element
        typedef typename Qualified<T>::Tconst_reference Tconst_reference;
        //! Type to be used as data representation
        typedef typename Qualified<T>::Tmutable_value Tmutable_value;
127
128
        //! Type to pass externally managed pointer to counted reference object
        typedef typename Qualified<T>::Tmutable_pointer Tmutable_pointer;
129
130
131
132
        //! Type to be used as element for const version
        typedef typename Qualified<T>::Tconst_value Tconst_value;
        //! Type of const version of SharedHeap
        typedef SharedHeap<Tconst_value> Tcontainer_of_const;
thomas.forbriger's avatar
thomas.forbriger committed
133
134
        //! short for container of const
        typedef SharedHeap<Tconst_value> Tcoc;
135
136
137
138
139
140
141
142
143
144
145
146

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

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

        //! Allocate new heap memory.
        SharedHeap(const Tsize& size);

147
148
149
        //! Create representation for externally managed memory
        SharedHeap(Tpointer* pointer, const Tsize& size);

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
        //! Copy representation to share heap.
        SharedHeap(const SharedHeap& sharedheap);

        //! Copy representation to share heap.
        SharedHeap(Theapstruct* heapstruct);

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

        //! Copy representation to share heap.
        SharedHeap& operator=(const SharedHeap& 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
         */
        Tpointer array();

        //! Index operator (always inline).
        inline
        Treference operator[](const Tsubscript& i) 
        { 
178
#ifdef AFF_INDEXCHECK
179
180
181
182
183
184
185
186
187
188
189
190
191
          int ii=i;
          if ((ii>=int(Mheapstruct->Msize)) || (ii<0))
          {
            throw "SharedHeap: illegal index position!";
          }
#endif
          return(Mheapstruct->Mheap[i]); 
        }

        //! Index operator (always inline).
        inline
        Tconst_reference operator[](const Tsubscript& i) const
        { 
192
#ifdef AFF_INDEXCHECK
193
194
195
196
197
198
199
200
201
          int ii=i;
          if ((ii>=int(Mheapstruct->Msize)) || (ii<0))
          {
            throw "SharedHeap: illegal index position!";
          }
#endif
          return(Mheapstruct->Mheap[i]); 
        }

thomas.forbriger's avatar
thomas.forbriger committed
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
        /*! conversion operator
         *
         * \note
         * This conversion operation does not work when passing a reference to
         * a function! Declaring a function
         * \code
         *   void func(const aff::SharedHeap<T>::Tcoc& sh);
         * \endcode
         * is useless. It will not implicitely convert a \c aff::SharedHeap<T>
         * to a \c aff::SharedHeap<T>::Tcoc, because they are indipendent
         * types which means a temporary object of type
         * aff::SharedHeap<T>::Tcoc must be created. This only works with
         * \code
         *   void func(aff::SharedHeap<T>::Tcoc sh);
         * \endcode
         * which is passing by value.
         */
219
220
221
222
223
224
225
226
227
228
        operator Tcontainer_of_const() const
        {
          Tcontainer_of_const retval(Mheapstruct);
          return(retval);
        }

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

229
230
#ifdef AFF_PREBUILT
} // namespace prebuilt
231
232
#endif

233
} // namespace aff
234

235
236
#ifndef AFF_NO_DEFINITIONS
#include <aff/lib/sharedheap_def.h>
237
238
#endif

239
#endif // AFF_SHAREDHEAP_H_VERSION (includeguard)
240
241

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