1 /***************************************************************************
2     begin       : Mon Jul 14 2008
3     copyright   : (C) 2008 by Martin Preuss
4     email       : martin@libchipcard.de
5 
6  ***************************************************************************
7  *                                                                         *
8  *   This library is free software; you can redistribute it and/or         *
9  *   modify it under the terms of the GNU Lesser General Public            *
10  *   License as published by the Free Software Foundation; either          *
11  *   version 2.1 of the License, or (at your option) any later version.    *
12  *                                                                         *
13  *   This library is distributed in the hope that it will be useful,       *
14  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
15  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
16  *   Lesser General Public License for more details.                       *
17  *                                                                         *
18  *   You should have received a copy of the GNU Lesser General Public      *
19  *   License along with this library; if not, write to the Free Software   *
20  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
21  *   MA  02111-1307  USA                                                   *
22  *                                                                         *
23  ***************************************************************************/
24 
25 #ifndef GWENHYWFAR_MEMCACHE_H
26 #define GWENHYWFAR_MEMCACHE_H
27 
28 
29 #include <gwenhywfar/gwenhywfarapi.h>
30 
31 #include <time.h>
32 #include <inttypes.h>
33 
34 
35 
36 typedef struct GWEN_MEMCACHE_ENTRY GWEN_MEMCACHE_ENTRY;
37 
38 typedef struct GWEN_MEMCACHE GWEN_MEMCACHE;
39 
40 
41 GWENHYWFAR_API
42 void GWEN_MemCacheEntry_free(GWEN_MEMCACHE_ENTRY *me);
43 
44 GWENHYWFAR_API
45 uint32_t GWEN_MemCacheEntry_GetId(GWEN_MEMCACHE_ENTRY *me);
46 
47 
48 GWENHYWFAR_API
49 void *GWEN_MemCacheEntry_GetDataPtr(GWEN_MEMCACHE_ENTRY *me);
50 
51 GWENHYWFAR_API
52 size_t GWEN_MemCacheEntry_GetDataLen(GWEN_MEMCACHE_ENTRY *me);
53 
54 GWENHYWFAR_API
55 int GWEN_MemCacheEntry_GetIsValid(const GWEN_MEMCACHE_ENTRY *me);
56 
57 GWENHYWFAR_API
58 void GWEN_MemCacheEntry_BeginUse(GWEN_MEMCACHE_ENTRY *me);
59 
60 GWENHYWFAR_API
61 void GWEN_MemCacheEntry_EndUse(GWEN_MEMCACHE_ENTRY *me);
62 
63 
64 
65 
66 GWENHYWFAR_API
67 GWEN_MEMCACHE *GWEN_MemCache_new(size_t maxCacheMemory,
68                                  uint32_t maxCacheEntries);
69 
70 GWENHYWFAR_API
71 void GWEN_MemCache_free(GWEN_MEMCACHE *mc);
72 
73 
74 /**
75  * Returns the cache entry with the given id (if any).
76  * If NULL is returned then there is no entry with the given id,
77  * otherwise the use counter of the object returned is incremented.
78  * Therefore the caller has to call @ref GWEN_MemCacheEntry_EndUse
79  * after working with the object returned in order to release unused
80  * cache entries.
81  */
82 GWENHYWFAR_API
83 GWEN_MEMCACHE_ENTRY *GWEN_MemCache_FindEntry(GWEN_MEMCACHE *mc,
84                                              uint32_t id);
85 
86 /**
87  * Creates a cache entry for the given id. If there already is an entry
88  * of the given id that existing entry will first be invalidated.
89  * The use counter of the new object returned is 1, so the caller must
90  * call @ref GWEN_MemCacheEntry_EndUse after working with the object returned in
91  * order to release unused cache entries.
92  */
93 GWENHYWFAR_API
94 GWEN_MEMCACHE_ENTRY *GWEN_MemCache_CreateEntry(GWEN_MEMCACHE *mc,
95                                                uint32_t id,
96                                                void *dataPtr,
97                                                size_t dataLen);
98 
99 /**
100  * This function invalidates a given cache entry (if it exists).
101  * The data associated with that entry is not freed yet until all
102  * users of that entry called @ref GWEN_MemCacheEntry_EndUse (i.e.
103  * until the use counter of that entry reaches zero). However, the
104  * entry will be removed from the cache index so that future calls
105  * to @ref GWEN_MemCache_FindEntry will not return it.
106  */
107 GWENHYWFAR_API
108 void GWEN_MemCache_PurgeEntry(GWEN_MEMCACHE *mc,
109                               uint32_t id);
110 
111 /**
112  * This function invalidates all entries whose ids match the given
113  * id/mask pair. See @ref GWEN_MemCache_PurgeEntry for implementation
114  * details and caveats.
115  */
116 GWENHYWFAR_API
117 void GWEN_MemCache_PurgeEntries(GWEN_MEMCACHE *mc,
118                                 uint32_t id, uint32_t mask);
119 
120 /**
121  * This function invalidates all cache entries.
122  * See @ref GWEN_MemCache_PurgeEntry for implementation
123  * details and caveats.
124  */
125 GWENHYWFAR_API
126 void GWEN_MemCache_Purge(GWEN_MEMCACHE *mc);
127 
128 
129 
130 
131 
132 #endif
133