Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added documentation on the cache interface

  • Loading branch information...
commit 652884e33425aca52be61438482fc0b6f9b5ab08 1 parent 4c86fa5
Trond Norbye authored dustin committed

Showing 1 changed file with 79 additions and 7 deletions. Show diff stats Hide diff stats

  1. +79 7 cache.h
86 cache.h
@@ -18,27 +18,99 @@
18 18 extern int cache_error;
19 19 #endif
20 20
21   -typedef int cache_constructor_t(void *, void *, int);
22   -typedef void cache_destructor_t(void *, void *);
  21 +/**
  22 + * Constructor used to initialize allocated objects
  23 + *
  24 + * @param obj pointer to the object to initialized.
  25 + * @param notused1 This parameter is currently not used.
  26 + * @param notused2 This parameter is currently not used.
  27 + * @return you should return 0, but currently this is not checked
  28 + */
  29 +typedef int cache_constructor_t(void* obj, void* notused1, int notused2);
  30 +/**
  31 + * Destructor used to clean up allocated objects before they are
  32 + * returned to the operating system.
  33 + *
  34 + * @param obj pointer to the object to initialized.
  35 + * @param notused1 This parameter is currently not used.
  36 + * @param notused2 This parameter is currently not used.
  37 + * @return you should return 0, but currently this is not checked
  38 + */
  39 +typedef void cache_destructor_t(void* obj, void* notused);
23 40
  41 +/**
  42 + * Definition of the structure to keep track of the internal details of
  43 + * the cache allocator. Touching any of these variables results in
  44 + * undefined behavior.
  45 + */
24 46 typedef struct {
  47 + /** Mutex to protect access to the structure */
25 48 pthread_mutex_t mutex;
  49 + /** Name of the cache objects in this cache (provided by the caller) */
26 50 char *name;
  51 + /** List of pointers to available buffers in this cache */
27 52 void **ptr;
  53 + /** The size of each element in this cache */
28 54 size_t bufsize;
  55 + /** The capacity of the list of elements */
29 56 int freetotal;
  57 + /** The current number of free elements */
30 58 int freecurr;
  59 + /** The constructor to be called each time we allocate more memory */
31 60 cache_constructor_t* constructor;
  61 + /** The destructor to be called each time before we release memory */
32 62 cache_destructor_t* destructor;
33 63 } cache_t;
34 64
35   -
36   -cache_t* cache_create(const char *name, size_t bufsize, size_t align,
  65 +/**
  66 + * Create an object cache.
  67 + *
  68 + * The object cache will let you allocate objects of the same size. It is fully
  69 + * MT safe, so you may allocate objects from multiple threads without having to
  70 + * do any syncrhonization in the application code.
  71 + *
  72 + * @param name the name of the object cache. This name may be used for debug purposes
  73 + * and may help you track down what kind of object you have problems with
  74 + * (buffer overruns, leakage etc)
  75 + * @param bufsize the size of each object in the cache
  76 + * @param align the alignment requirements of the objects in the cache.
  77 + * @param constructor the function to be called to initialize memory when we need
  78 + * to allocate more memory from the os.
  79 + * @param destructor the function to be called before we release the memory back
  80 + * to the os.
  81 + * @return a handle to an object cache if successful, NULL otherwise.
  82 + */
  83 +cache_t* cache_create(const char* name, size_t bufsize, size_t align,
37 84 cache_constructor_t* constructor,
38 85 cache_destructor_t* destructor);
39   -void cache_destroy(cache_t*);
40   -void* cache_alloc(cache_t*);
41   -void cache_free(cache_t*, void*);
  86 +/**
  87 + * Destroy an object cache.
  88 + *
  89 + * Destroy and invalidate an object cache. You should return all buffers allocated
  90 + * with cache_alloc by using cache_free before calling this function. Not doing
  91 + * so results in undefined behavior (the buffers may or may not be invalidated)
  92 + *
  93 + * @param handle the handle to the object cache to destroy.
  94 + */
  95 +void cache_destroy(cache_t* handle);
  96 +/**
  97 + * Allocate an object from the cache.
  98 + *
  99 + * @param handle the handle to the object cache to allocate from
  100 + * @return a pointer to an initialized object from the cache, or NULL if
  101 + * the allocation cannot be satisfied.
  102 + */
  103 +void* cache_alloc(cache_t* handle);
  104 +/**
  105 + * Return an object back to the cache.
  106 + *
  107 + * The caller should return the object in an initialized state so that
  108 + * the object may be returned in an expected state from cache_alloc.
  109 + *
  110 + * @param handle handle to the object cache to return the object to
  111 + * @param ptr pointer to the object to return.
  112 + */
  113 +void cache_free(cache_t* handle, void* ptr);
42 114 #endif
43 115
44 116 #endif

0 comments on commit 652884e

Please sign in to comment.
Something went wrong with that request. Please try again.