1 /* @include enscache **********************************************************
2 **
3 ** Ensembl Cache functions
4 **
5 ** @author Copyright (C) 1999 Ensembl Developers
6 ** @author Copyright (C) 2006 Michael K. Schuster
7 ** @version $Revision: 1.23 $
8 ** @modified 2009 by Alan Bleasby for incorporation into EMBOSS core
9 ** @modified $Date: 2012/08/05 10:30:58 $ by $Author: mks $
10 ** @@
11 **
12 ** This library is free software; you can redistribute it and/or
13 ** modify it under the terms of the GNU Lesser General Public
14 ** License as published by the Free Software Foundation; either
15 ** version 2.1 of the License, or (at your option) any later version.
16 **
17 ** This library is distributed in the hope that it will be useful,
18 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
20 ** Lesser General Public License for more details.
21 **
22 ** You should have received a copy of the GNU Lesser General Public
23 ** License along with this library; if not, write to the Free Software
24 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
25 ** MA  02110-1301,  USA.
26 **
27 ******************************************************************************/
28 
29 #ifndef ENSCACHE_H
30 #define ENSCACHE_H
31 
32 /* ========================================================================= */
33 /* ============================= include files ============================= */
34 /* ========================================================================= */
35 
36 #include "ajax.h"
37 
38 AJ_BEGIN_DECLS
39 
40 
41 
42 
43 /* ========================================================================= */
44 /* =============================== constants =============================== */
45 /* ========================================================================= */
46 
47 /* @enum EnsECacheType ********************************************************
48 **
49 ** Ensembl Cache Type enumeration
50 **
51 ** @value ensECacheTypeNULL Null
52 ** @value ensECacheTypeNumeric Numeric
53 ** @value ensECacheTypeAlphaNumeric Alphanumeric
54 ** @@
55 ******************************************************************************/
56 
57 typedef enum EnsOCacheType
58 {
59     ensECacheTypeNULL,
60     ensECacheTypeNumeric,
61     ensECacheTypeAlphaNumeric
62 } EnsECacheType;
63 
64 
65 
66 
67 /* ========================================================================= */
68 /* ============================== public data ============================== */
69 /* ========================================================================= */
70 
71 /* @data EnsPCache ************************************************************
72 **
73 ** Ensembl Cache.
74 **
75 ** @alias EnsSCache
76 ** @alias EnsOCache
77 **
78 ** @attr Label [AjPStr] Cache label for statistics output
79 ** @attr List [AjPList] AJAX List implementing LRU functionality
80 ** @attr Table [AjPTable] AJAX Table implementing lookup functionality
81 ** @attr Freference [void* function] Object-specific referencing function
82 ** @attr Fdelete [void function] Object-specific deletion function
83 ** @attr Fsize [size_t function] Object-specific memory sizing function
84 ** @attr Fread [void* function] Object-specific reading function
85 ** @attr Fwrite [AjBool function] Object-specific writing function
86 ** @attr Type [EnsECacheType] Ensembl Cache type
87 ** @attr Synchron [AjBool] ajTrue: Immediately write-back value data
88 **                         ajFalse: Write-back value data later
89 ** @cc Memory limits
90 ** @attr Bytes [size_t] Current number of cached bytes
91 ** @attr MaxBytes [size_t] Maximum number of allowed bytes
92 ** @attr MaxSize [size_t] Maximum memory size of an object
93 ** @cc Counter limits
94 ** @attr Count [ajuint] Current number of cached entry
95 ** @attr MaxCount [ajuint] Maximum number of allowed entries
96 ** @cc Performance statistics
97 ** @attr Dropped [ajuint] Number of entries dropped by the LRU algorithm
98 ** @attr Removed [ajuint] Number of entries explicitly removed
99 ** @attr Stored [ajuint] Number of entries currently stored
100 ** @attr Hit [ajuint] Number of cache hits
101 ** @attr Miss [ajuint] Number of cache misses
102 ** @attr Padding [ajuint] Padding to alignment boundary
103 ** @@
104 ******************************************************************************/
105 
106 typedef struct EnsSCache
107 {
108     AjPStr Label;
109     AjPList List;
110     AjPTable Table;
111     void *(*Freference) (void *value);
112     void (*Fdelete) (void **Pvalue);
113     size_t (*Fsize) (const void *value);
114     void *(*Fread) (const void *key);
115     AjBool (*Fwrite) (const void *value);
116     EnsECacheType Type;
117     AjBool Synchron;
118     size_t Bytes;
119     size_t MaxBytes;
120     size_t MaxSize;
121     ajuint Count;
122     ajuint MaxCount;
123     ajuint Dropped;
124     ajuint Removed;
125     ajuint Stored;
126     ajuint Hit;
127     ajuint Miss;
128     ajuint Padding;
129 } EnsOCache;
130 
131 #define EnsPCache EnsOCache*
132 
133 
134 
135 
136 /* ========================================================================= */
137 /* =========================== public functions ============================ */
138 /* ========================================================================= */
139 
140 /*
141 ** Prototype definitions
142 */
143 
144 /* Ensembl Cache */
145 
146 EnsPCache ensCacheNew(const EnsECacheType type,
147                       size_t maxbytes,
148                       ajuint maxcount,
149                       size_t maxsize,
150                       void *(*Freference) (void *value),
151                       void (*Fdelete) (void **Pvalue),
152                       size_t (*Fsize) (const void *value),
153                       void *(*Fread) (const void *key),
154                       AjBool (*Fwrite) (const void *value),
155                       AjBool synchron,
156                       const char *label);
157 
158 void ensCacheDel(EnsPCache *Pcache);
159 
160 AjBool ensCacheClear(EnsPCache cache);
161 
162 AjBool ensCacheTrace(const EnsPCache cache, ajuint level);
163 
164 AjBool ensCacheFetch(EnsPCache cache, void *key, void **Pvalue);
165 
166 AjBool ensCacheRemove(EnsPCache cache, const void *key);
167 
168 AjBool ensCacheStore(EnsPCache cache, void *key, void **Pvalue);
169 
170 AjBool ensCacheSynchronise(EnsPCache cache);
171 
172 /*
173 ** End of prototype definitions
174 */
175 
176 
177 
178 
179 AJ_END_DECLS
180 
181 #endif /* !ENSCACHE_H */
182