summaryrefslogtreecommitdiff
path: root/ACE/ace/Cache_Map_Manager_T.h
blob: 6a75854df24299765bde1cb3b363bab3e03c9723 (plain)
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
// -*- C++ -*-

//=============================================================================
/**
 *  @file    Cache_Map_Manager_T.h
 *
 *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
 */
//=============================================================================

#ifndef ACE_CACHE_MAP_MANAGER_T_H
#define ACE_CACHE_MAP_MANAGER_T_H

#include /**/ "ace/pre.h"

#include /**/ "ace/config-all.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#include "ace/Default_Constants.h"
#include "ace/Global_Macros.h"
#include "ace/Pair_T.h"

ACE_BEGIN_VERSIONED_NAMESPACE_DECL

// Forward declaration.
class ACE_Allocator;

#define ACE_Cache_Map_Iterator ACMI
#define ACE_Cache_Map_Reverse_Iterator ACMRI

template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
class ACE_Cache_Map_Iterator;

template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
class ACE_Cache_Map_Reverse_Iterator;

// For linkers that cant grok long names.
#define ACE_Cache_Map_Manager ACMM

/**
 * @class ACE_Cache_Map_Manager
 *
 * @brief Defines a abstraction that will purge entries from a map.
 *
 * The <ACE_Cache_Map_Manager> will manage the map it contains
 * and provide purging on demand from the map. The strategy for
 * caching is decided by the user and provided to the Cache
 * Manager.  The Cache Manager acts as a agent and communicates
 * between the Map and the Strategy for purging entries from the
 * map.
 * No locking mechanism provided since locking at this level
 * isn't efficient.  Locking has to be provided by the
 * application.
 */
template <class KEY, class VALUE, class CMAP_TYPE, class ITERATOR_IMPL, class REVERSE_ITERATOR_IMPL, class CACHING_STRATEGY, class ATTRIBUTES>
class ACE_Cache_Map_Manager
{
public:
  // = Traits.
  typedef KEY key_type;
  typedef VALUE mapped_type;
  typedef CMAP_TYPE map_type;
  typedef CACHING_STRATEGY caching_strategy_type;

  typedef ITERATOR_IMPL ITERATOR_IMPLEMENTATION;
  typedef REVERSE_ITERATOR_IMPL REVERSE_ITERATOR_IMPLEMENTATION;

  friend class ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;
  friend class ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>;

  // = ACE-style iterator typedefs.
  typedef ACE_Cache_Map_Iterator<KEY, VALUE, ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>
          ITERATOR;
  typedef ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_ITERATOR_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES>
          REVERSE_ITERATOR;

   // = STL-style iterator typedefs.
  typedef ITERATOR
          iterator;
  typedef REVERSE_ITERATOR
          reverse_iterator;

  /**
   * The actual value mapped to the key in the map. The <attributes>
   * are used by the strategy and is transparent to the user of this
   * class.
   */
  typedef std::pair<VALUE, ATTRIBUTES> CACHE_VALUE;

  /// Initialize a <Cache_Map_Manager> with <caching_strategy> and
  /// @a size entries.
  ACE_Cache_Map_Manager (CACHING_STRATEGY &caching_strategy,
                         size_t size = ACE_DEFAULT_MAP_SIZE,
                         ACE_Allocator *alloc = nullptr);

  /// Close down a <Cache_Map_Manager> and release dynamically allocated
  /// resources.
  virtual ~ACE_Cache_Map_Manager (void);

  /// Initialize a cache with size @a length.
  int open (size_t length = ACE_DEFAULT_MAP_SIZE,
            ACE_Allocator *alloc = nullptr);

  /// Close down a cache and release dynamically allocated resources.
  int close (void);

  /**
   * Associate @a key with @a value.  If @a key is already in the CMAP_TYPE
   * then the ENTRY is not changed.  Returns 0 if a new entry is bound
   * successfully, returns 1 if an attempt is made to bind an existing
   * entry, and returns -1 if failures occur.
   */
  int bind (const KEY &key,
            const VALUE &value);

  /**
   * Lookup entry<key,value> in the cache. If it is not found, returns -1.
   * If the @a key is located in the CMAP_TYPE object, the CACHING_STRATEGY is
   * notified of it via notify_find (int result, ATTRIBUTES &attribute).
   * If notify_find also returns 0 (success), then this function returns
   * 0 (success) and sets the cached value in @a value.
   */
  int find (const KEY &key,
            VALUE &value);

  /**
   * Lookup entry<key,value> in the cache. If it is not found, returns -1.
   * If the @a key is located in the CMAP_TYPE object, the CACHING_STRATEGY is
   * notified of it via notify_find (int result, ATTRIBUTES &attribute).
   * If notify_find also returns 0 (success), then this function returns
   * 0 (success).
   */
  int find (const KEY &key);

  /**
   * Reassociate the @a key with @a value. If the @a key already exists
   * in the cache then returns 1, on a new bind returns 0 and returns
   * -1 in case of any failures.
   */
  int rebind (const KEY &key,
              const VALUE &value);

  /**
   * Reassociate @a key with @a value, storing the old value into the
   * "out" parameter @a old_value.  The function fails if @a key is not
   * in the cache for caches that do not allow user specified keys.
   * However, for caches that allow user specified keys, if the key is
   * not in the cache, a new @a key / @a value association is created.
   */
  int rebind (const KEY &key,
              const VALUE &value,
              VALUE &old_value);

  /**
   * Reassociate @a key with @a value, storing the old key and value
   * into the "out" parameters @a old_key and @a old_value.  The
   * function fails if @a key is not in the cache for caches that do
   * not allow user specified keys.  However, for caches that allow
   * user specified keys, if the key is not in the cache, a new
   * @a key / @a value association is created.
   */
  int rebind (const KEY &key,
              const VALUE &value,
              KEY &old_key,
              VALUE &old_value);

  /**
   * Associate @a key with @a value if and only if @a key is not in the
   * cache.  If @a key is already in the cache, then the @a value
   * parameter is overwritten with the existing value in the
   * cache. Returns 0 if a new @a key / @a value association is created.
   * Returns 1 if an attempt is made to bind an existing entry.  This
   * function fails for maps that do not allow user specified keys.
   */
  int trybind (const KEY &key,
               VALUE &value);

  /// Remove @a key from the cache.
  int unbind (const KEY &key);

  /// Remove @a key from the cache, and return the @a value associated with
  /// @a key.
  int unbind (const KEY &key,
              VALUE &value);

  /// Remove entries from the cache depending upon the strategy.
  int purge (void);

  /// Return the current size of the cache.
  size_t current_size () const;

  /// Return the total size of the cache.
  size_t total_size () const;

  /// Dumps the state of the object.
  void dump () const;

  // = STL styled iterator factory functions.

  /// Return forward iterator.
  ITERATOR begin (void);
  ITERATOR end (void);

  /// Return reverse iterator.
  REVERSE_ITERATOR rbegin (void);
  REVERSE_ITERATOR rend (void);

  /// The map managed by the Cache_Map_Manager.
  CMAP_TYPE &map (void);

  /// The caching strategy used on the cache.
  CACHING_STRATEGY &caching_strategy (void);

  /// Declare the dynamic allocation hooks.
  ACE_ALLOC_HOOK_DECLARE;

protected:

  /// The underlying map which needs to be cached.
  CMAP_TYPE map_;

  /// The strategy to be followed for caching entries in the map.
  CACHING_STRATEGY &caching_strategy_;

private:
  // = Disallow these operations.
  void operator= (const ACE_Cache_Map_Manager<KEY, VALUE, CMAP_TYPE, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES> &) = delete;
  ACE_Cache_Map_Manager (const ACE_Cache_Map_Manager<KEY, VALUE, CMAP_TYPE, ITERATOR_IMPL, REVERSE_ITERATOR_IMPL, CACHING_STRATEGY, ATTRIBUTES> &) = delete;
};

/**
 * @class ACE_Cache_Map_Iterator
 *
 * @brief Defines a iterator for the Cache_Map_Manager.
 *
 * Implementation to be provided by the iterator of the map
 * managed by the ACE_Cache_Map_Manager.
 */
template <class KEY, class VALUE, class IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
class ACE_Cache_Map_Iterator
{
public:
  // = Traits.
  /// The actual value mapped to the key in the cache. The <attributes>
  /// are used by the strategy and is transparent to the cache user.
  typedef ACE_Reference_Pair<KEY, VALUE>
          value_type;
  typedef std::pair <VALUE, ATTRIBUTES>
          CACHE_VALUE;

  // = Initialisation and termination methods.

  ACE_Cache_Map_Iterator (const IMPLEMENTATION &iterator_impl);

  /// Copy constructor.
  ACE_Cache_Map_Iterator (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);

  virtual ~ACE_Cache_Map_Iterator (void);

  // = Iteration methods.

  /// assignment operator.
  ACE_Cache_Map_Iterator <KEY, VALUE, IMPLEMENTATION,
                          CACHING_STRATEGY, ATTRIBUTES> &operator=
      (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION,
                                    CACHING_STRATEGY, ATTRIBUTES> &rhs);

  /// Comparison operators.
  bool operator== (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
  bool operator!= (const ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;

  /// Returns a reference to the internal element @c this is pointing
  /// to.
  ACE_Reference_Pair<KEY, VALUE> operator* () const;

  // = STL styled iteration, compare, and reference functions.

  /// Prefix advance
  ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void);

  /// Postfix advance.
  ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);

  /// Prefix reverse.
  ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void);

  /// Postfix reverse.
  ACE_Cache_Map_Iterator<KEY, VALUE, IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);

  /// Returns the iterator of the internal map in the custody of the
  /// Cache_Map_Manager.
  IMPLEMENTATION &iterator_implementation (void);

  /// Dump the state of an object.
  void dump () const;

  /// Declare the dynamic allocation hooks.
  ACE_ALLOC_HOOK_DECLARE;

protected:
  /// The actual iterator which iterates internally on the map
  /// belonging to the Cache_Map_Manager.
  IMPLEMENTATION iterator_implementation_;
};

/**
 * @class ACE_Cache_Map_Reverse_Iterator
 *
 * @brief Defines a reverse iterator for the Cache_Map_Manager.
 *
 * Implementation to be provided by the reverse iterator of the map
 * managed by thr Cache_Map_manager.
 */
template <class KEY, class VALUE, class REVERSE_IMPLEMENTATION, class CACHING_STRATEGY, class ATTRIBUTES>
class ACE_Cache_Map_Reverse_Iterator
{
public:
  // = Traits.
  /// The actual value mapped to the key in the cache. The <attributes>
  /// are used by the strategy and is transparent to the cache user.
  typedef ACE_Reference_Pair<KEY, VALUE> value_type;
  typedef std::pair <VALUE, ATTRIBUTES> CACHE_VALUE;

  // = Initialisation and termination methods.

  ACE_Cache_Map_Reverse_Iterator (const REVERSE_IMPLEMENTATION &iterator_impl);

  /// Copy constructor.
  ACE_Cache_Map_Reverse_Iterator (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs);

  ~ACE_Cache_Map_Reverse_Iterator (void);

  // = Iteration methods.

  /// Assignment operator.
  ACE_Cache_Map_Reverse_Iterator <KEY, VALUE, REVERSE_IMPLEMENTATION,
                                  CACHING_STRATEGY, ATTRIBUTES> &operator=
     (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION,
                                           CACHING_STRATEGY, ATTRIBUTES> &rhs);

  /// Comparison operators.
  bool operator== (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;
  bool operator!= (const ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &rhs) const;

  /// Returns a reference to the internal element @c this is pointing
  /// to.
  ACE_Reference_Pair<KEY, VALUE> operator* () const;

  // = STL styled iteration, compare, and reference functions.

  /// Prefix advance
  ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator++ (void);

  /// Postfix advance.
  ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator++ (int);

  /// Prefix reverse.
  ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> &operator-- (void);

  /// Postfix reverse.
  ACE_Cache_Map_Reverse_Iterator<KEY, VALUE, REVERSE_IMPLEMENTATION, CACHING_STRATEGY, ATTRIBUTES> operator-- (int);

  /// Returns the iterator of the internal map in the custody of the
  /// Cache_Map_Manager.
  REVERSE_IMPLEMENTATION &iterator_implementation (void);

  /// Dump the state of an object.
  void dump () const;

  /// Declare the dynamic allocation hooks.
  ACE_ALLOC_HOOK_DECLARE;

protected:
  /// The actual iterator which iterates internally on the map
  /// belonging to the Cache_Map_Manager.
  REVERSE_IMPLEMENTATION reverse_iterator_implementation_;
};

ACE_END_VERSIONED_NAMESPACE_DECL

#if defined (__ACE_INLINE__)
#include "ace/Cache_Map_Manager_T.inl"
#endif /* __ACE_INLINE__ */

#if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
#include "ace/Cache_Map_Manager_T.cpp"
#endif /* ACE_TEMPLATES_REQUIRE_SOURCE */

#if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
#pragma implementation ("Cache_Map_Manager_T.cpp")
#endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */

#include /**/ "ace/post.h"

#endif /* ACE_CACHE_MAP_MANAGER_T_H */