C++ bindings for cgul_cache
More...
#include <cgul_cache_cxx.h>
Public Types | |
| typedef cgul_cache__constructor_t | constructor_t |
| typedef cgul_cache__destructor_t | destructor_t |
| typedef cgul_cache__restructor_t | restructor_t |
Public Member Functions | |
| cgul_cache_cxx (constructor_t constructor, destructor_t destructor, restructor_t restructor) | |
| cgul_cache_cxx (cgul_cache_t rhs) | |
| virtual | ~cgul_cache_cxx () |
| virtual unsigned long int | get_size () const |
| virtual void | set_size (unsigned long int size) |
| virtual unsigned long int | get_reserve () const |
| virtual void | set_reserve (unsigned long int reserve) |
| virtual void * | get () |
| virtual void | put (void *o) |
| virtual cgul_cache_t | get_obj () const |
| virtual cgul_cache_t | take_obj () |
| virtual void | set_obj (cgul_cache_t rhs) |
Static Public Member Functions | |
| static cgul_cache_t | get_freer () |
Detailed Description
This class provides the C++ bindings for C cgul_cache objects. The main purpose of this class is to convert the C-style function calls and exception handling in cgul_cache into C++-style function calls and exception handling.
Member Typedef Documentation
§ constructor_t
This function pointer typedef is needed so that the cgul_cache_cxx knows how to create new default instances of the objects you want to cache.
§ destructor_t
This function pointer typedef is needed so that the cgul_cache_cxx knows how to delete instances of the objects you want to cache. The client's implementation of this function should not throw an exception.
§ restructor_t
This function pointer typedef is needed so that the cgul_cache_cxx knows how take a fully constructed object and return it to its initial default state. This callback is invoked when objects are put back on the cache to minimize the memory footprint of objects on the cache. If the restructor is set to NULL, the client is responsible for resetting the object before putting it back on the cgul_cache.
Constructor & Destructor Documentation
§ cgul_cache_cxx() [1/2]
|
inline |
Create a new cgul_cache_cxx instance. If restructor is set to NULL, the client is responsible for resetting the object before putting it back on the cgul_cache_cxx. If memory cannot be allocated, an exception is thrown.
By default, the maximum cache size is set to 0. This means no objects are cached by default. When you want to enable caching, you can change the maximum cache size by calling set_size().
- Parameters
-
[in] constructor constructor for the cached objects [in] destructor destructor for the cached objects [in] restructor restructor for the cached objects
References cgul_cache__new().
Referenced by set_obj().
§ cgul_cache_cxx() [2/2]
|
inline |
Create a new cgul_cache_cxx object by wrapping an existing cgul_cache object.
- Parameters
-
[in] rhs right-hand side
§ ~cgul_cache_cxx()
|
inlinevirtual |
This method first calls the destructor for each object that is still cached. It then frees all of its internally allocated resources.
References cgul_cache__delete().
Member Function Documentation
§ get_freer()
|
inlinestatic |
Static method used to return the cgul_cache instance that is an adapter for free(). Because the object returned is statically allocated, the client should not attempt to call cgul_cache__delete() on the pointer returned. If the client forgets, cgul_cache__delete() will ignore the request.
The purpose of this static method is to allow clients to use methods (like cgul_rbtree_cxx::remove_range()) that accept cgul_cache_cxx objects for cleaning up keys or values even though the objects are allocated directly using one of the malloc() family of function calls (instead of through the cgul_cache interface).
The cgul_cache object returned only implements the destructor_t part of the cgul_cache interface. Thus, any attempt to use the object returned to construct a new object will result in NULL being returned.
Because portable C++ has limitations with respect to initializing static members, this static method returns an instance of cgul_cache instead of an instance of cgul_cache_cxx. Thus, the user is required to wrap the return value as follows:
cgul_cache_cxx freer(cgul_cache_cxx::get_freer());
trie.clear(&freer, NULL);
- Returns
cgul_cacheadopter forfree()
References cgul_cache__get_freer().
§ get_size()
|
inlinevirtual |
Get the maximum number of objects the cache can hold when the reserve is zero. To get the total number of elements the cache can hold, you must add the reserve to the size.
- Returns
- maximum size of the cache
References cgul_cache__get_size().
§ set_size()
|
inlinevirtual |
Set the maximum number of objects the cache can hold when the reserve is zero.
Calling this method with size less than the reserve does not free any of the reserved objects; however, it may free objects that have recently been "moved" from the reserve to the main cache. (See set_reserve().)
You can release all the cached objects and disable caching of objects by setting the cache reserve to 0 and the cache size to 0 (in that order). This is the default.
If an error occurs (while enlarging the cache), an exception is thrown.
- Parameters
-
[in] size maximum size of the cache
References cgul_cache__set_size().
§ get_reserve()
|
inlinevirtual |
Get the reserve limit. This is the number of objects that are guaranteed to be held in reserve by the cache. These objects will not be returned by the cache until the reserve is reduced. The reserve is independent of the size of the cache.
- Returns
- reserve
References cgul_cache__get_reserve().
§ set_reserve()
|
inlinevirtual |
Set the reserve limit. This method causes the cache to reserve objects. The reserved objects are held indefinitely until the reserve is reduced. The reserve is independent of the size of the cache.
It is important to understand that if these reserved objects are not already being held by the cache, the cache will instantiate them. This allows the client to immediately instantiate objects without having to worry about out-of-memory exceptions when the objects are used later.
Note that if you want to get a pointer to one of the reserved object, you first call set_reserve() to reduce the number of the reserved objects. This simply "moves" the now unreserved objects to the main cache of objects. You then immediately call get() to get an object from the main cache.
It is done like this so that you can code strictly in terms of get(). You can then reserve an object now and trigger when it is used later just by calling this method. The code that uses get() does not need to know anything about reserved objects. It will just naturally use them.
Objects that are "moved" from the reserve to the main cache are not guaranteed to be available if set_size() has since been called.
- Parameters
-
[in] reserve reserve
References cgul_cache__set_reserve().
§ get()
|
inlinevirtual |
Try to return a re-initialized object from the cache; if the cache is empty, a newly instantiated object will be returned instead. If an error occurs, an exception is thrown.
- Returns
- cached or new object
References cgul_cache__get().
§ put()
|
inlinevirtual |
Try to put o on the cache. If the cache is full, o will be delete instead.
- Parameters
-
[in] o objct to cache or delete
References cgul_cache__put().
§ get_obj()
|
inlinevirtual |
Get the underlying cgul_cache object.
- Returns
- underlying object
Referenced by cgul_list_cxx::clear(), cgul_rbtree_cxx::clear(), cgul_trie_cxx::clear(), cgul_list_cxx::remove_range(), and cgul_list_cxx::remove_value().
§ take_obj()
|
inlinevirtual |
Take the underlying cgul_cache object. This means the underlying object will not be deleted when the wrapper goes out of scope. Also, because you have taken the underlying object, no other methods should be called on this wrapper's instance. Lastly, after taking the underlying object, it is the caller's responsibility to delete the underlying object by calling cgul_cache__delete().
- Returns
- underlying object
§ set_obj()
|
inlinevirtual |
Set the new underlying object to rhs. This causes the old underlying object to be deleted which invalidates any outstanding pointers to or iterators for the old underlying object.
This instance takes ownership of rhs which means rhs will be automatically deleted when the C++ wrapper is deleted. To prevent automatic deletion of rhs, call take_obj() when the C++ wrapper is no longer needed.
- Parameters
-
[in] rhs right-hand side
References cgul_cache__delete(), and cgul_cache_cxx().
The documentation for this class was generated from the following file:
