javadoc style comments added to fifocache

server/fifocache.c

@@ -1,4 +1,4 @@
-/* 
+/*
  * Simple FIFO generic cache. (c) Radim Kolar 2003, 2009
  * This file is copyrighted as LGPL v2.1
  *
@@ -11,7 +11,19 @@
 #include <stdio.h>
 #include "fifocache.h"
 
-/* allocates a memory for new cache stucture and init it */
+/**
+ * Create new FIFO cache.
+ *
+ * Allocates a memory for new cache stucture and initialise it.
+ *
+ * @param cachesize cache size in number of entries
+ * @param entrysize size of one entry in bytes
+ * @param edf  entry destroy function
+ * @param kdf  key destroy function
+ * @param kcf  key compare function, must return zero for equals keys
+ * @return NULL or error, otherwise newly allocated fifocache structure
+ */
+
 struct FifoCache * f_cache_new(unsigned int cachesize,unsigned int entrysize,
     void (*edf) (void *),unsigned int keysize, void (*kdf) (void *), int (*kcf)(const void *,const void *))
 {
@@ -59,13 +71,30 @@ struct FifoCache * f_cache_new(unsigned int cachesize,unsigned int entrysize,
 
     return cache;
 }
-/* set memory profile functions */
+
+/**
+ * Set memory profile functions.
+ *
+ * Memory profile functions returns sizes of data referenced
+ * by keys or entries. In this cache entries and keys are fixed
+ * size.
+ *
+ * @param cache cache to operate on
+ * @param keysize returns size of key in bytes
+ * @param entrysize returns size of entry in bytes
+ */
 void f_cache_set_memory_profilers(struct FifoCache *cache,unsigned int (*keysize) (void *key),unsigned int (*entrysize) (void *entry))
 {
     cache->get_keysize=keysize;
     cache->get_entrysize=entrysize;
 }
 
+/**
+ * Prints cache memory usage and hit/miss ratio.
+ *
+ * @param cache cache to operate on
+ * @param f FILE to write results to
+ */ 
 void f_cache_stats(struct FifoCache *cache,FILE *f)
 {
     unsigned int i;
@@ -110,12 +139,29 @@ void f_cache_stats(struct FifoCache *cache,FILE *f)
 	    cache->cachesize,used,sizeof(struct FifoCache), cache->cachesize*cache->keysize,dkey,cache->cachesize*cache->entrysize,dentry,cache->hit,cache->miss);
 }
 
+/**
+ * Empty memory profiler function.
+ *
+ * Intended use is passing this function as argument to
+ * f_cache_set_memory_profilers.
+ *
+ * @return always 0
+ */
 unsigned int f_cache_void_profiler(void *anything)
 {
     return 0;
 }
 
-/* destroys cache without deallocationg of elements itself */
+/**
+ * Destroys cache without calling destructor function on
+ * keys or elements. 
+ *
+ * Keys and elements and cache control structure are zeroed and deallocated
+ * but if they pointed to another structures via pointers, then these
+ * structures are left intact.
+ *
+ * @param cache cache to be destroyed
+ */
 void f_cache_destroy(struct FifoCache *cache)
 {
     if(cache==NULL) return;
@@ -128,13 +174,20 @@ void f_cache_destroy(struct FifoCache *cache)
 	memset(cache->k_head,0,cache->keysize*cache->cachesize);
 	free(cache->k_head);
     }
-    cache->e_head=NULL;
-    cache->k_head=NULL;
+    memset(cache,0,sizeof(struct FifoCache);
     free(cache);
 }
 
-/* copy record into cache, free existing record */
-/* returns pointer to data entry in cache */
+/** 
+ * Copy record into cache replacing existing record.
+ *
+ * Always creates new record even if we already have record for key in
+ * cache.
+ * @param cache cache to put record into
+ * @param key key for record
+ * @param data data for record
+ * @return pointer to data entry in cache
+ */
 void * f_cache_put(struct FifoCache *cache,const void *key,const void *data)
 {
    void *where;
@@ -161,7 +214,14 @@ void * f_cache_put(struct FifoCache *cache,const void *key,const void *data)
    return where;
 }
 
-/* find element by key */
+/**
+ * Find element by key.
+ *
+ * Linear search is performed.
+ * @param cache used cache
+ * @param key key for finding data
+ * @return cached data or NULL 
+ */
 void *f_cache_find(struct FifoCache *cache,const void *key)
 {
     unsigned int i;
@@ -170,16 +230,24 @@ void *f_cache_find(struct FifoCache *cache,const void *key)
     if(cache->keysize==0) return NULL;
 
     for(i=0;i<cache->cachesize;i++)
+    {
 	if(!cache->k_compare_func(key,cache->k_head+i*cache->keysize))
 	{
 	    cache->hit++;
 	    return cache->e_head+i*cache->entrysize;
 	}
+    }
     cache->miss++;
     return NULL;
 }
 
-/* clear all elements from the cache */
+/**
+ *  clear all elements from the cache. 
+ *
+ *  Cache itself is not destroyed and destroy functions are called.
+ *
+ *  @param cache cache to be cleared
+ */
 void f_cache_clear(struct FifoCache *cache)
 {
     unsigned int i;
@@ -203,7 +271,17 @@ void f_cache_clear(struct FifoCache *cache)
     cache->hit=0;
     cache->miss=0;
 }
-/* find key for given entry */
+
+/**
+ *  find key for given entry.
+ *
+ *  Entry must been received from cache before. We also dont
+ *  check if data have not been overwriten by new content after receiving.
+ *
+ *  @param cache cache to search
+ *  @param entry entry to search
+ *  @return key for entry or NULL
+ */
 void * f_cache_get_key(struct FifoCache *cache,const void *entry)
 {
     unsigned int i;
@@ -216,7 +294,14 @@ void * f_cache_get_key(struct FifoCache *cache,const void *entry)
     return cache->k_head+cache->keysize*i;
 }
 
-/* delete entry from cache, returns one if object is deleted */
+/** 
+ * delete entry from cache. 
+ *
+ * Destroy function is called on entry.
+ * @param cache from what cache to delete entry
+ * @param entry entry to be deleted
+ * @return one if object is deleted
+ */
 int f_cache_delete_entry(struct FifoCache *cache, void *entry)
 {
     unsigned int i;
@@ -237,7 +322,13 @@ int f_cache_delete_entry(struct FifoCache *cache, void *entry)
     return 1;
 }
 
-/* returns how many objects was deleted */
+/**
+ * Perform searched delete
+ *
+ * @param cache cache to search
+ * @param key key used for deleting entries
+ * @return how many objects were deleted.
+ */
 int f_cache_delete_by_key(struct FifoCache *cache, void *key)
 {
     unsigned int i;