1/*-
2 * Copyright (c) 2005 Michael Bushkov <bushman@rsu.ru>
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 *    notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 *    notice, this list of conditions and the following disclaimer in the
12 *    documentation and/or other materials provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 * SUCH DAMAGE.
25 */
26
27#ifndef __NSCD_CACHELIB_H__
28#define __NSCD_CACHELIB_H__
29
30#include "hashtable.h"
31#include "cacheplcs.h"
32
33enum cache_entry_t	{
34	CET_COMMON = 0,	/* cache item is atomic */
35	CET_MULTIPART	/* cache item is formed part by part */
36};
37
38enum cache_transformation_t {
39	CTT_FLUSH = 0,	/* flush the cache - delete all obsolete items */
40	CTT_CLEAR = 1	/* delete all items in the cache */
41};
42
43/* cache deletion policy type enum */
44enum cache_policy_t {
45	CPT_FIFO = 0, 	/* first-in first-out */
46	CPT_LRU = 1,	/* least recently used */
47	CPT_LFU = 2 	/* least frequently used */
48};
49
50/* multipart sessions can be used for reading and writing */
51enum cache_mp_session_t {
52	CMPT_READ_SESSION,
53	CMPT_WRITE_SESSION
54};
55
56/*
57 * When doing partial transformations of entries (which are applied for
58 * elements with keys, that contain specified buffer in its left or
59 * right part), this enum will show the needed position of the key part.
60 */
61enum part_position_t {
62	KPPT_LEFT,
63	KPPT_RIGHT
64};
65
66/* num_levels attribute is obsolete, i think - user can always emulate it
67 * by using one entry.
68 * get_time_func is needed to have the clocks-independent counter
69 */
70struct cache_params {
71	void	(*get_time_func)(struct timeval *);
72};
73
74/*
75 * base structure - normal_cache_entry_params and multipart_cache_entry_params
76 * are "inherited" from it
77 */
78struct cache_entry_params {
79	enum cache_entry_t entry_type;
80	char	*entry_name;
81};
82
83/* params, used for most entries */
84struct common_cache_entry_params {
85	struct cache_entry_params cep;
86
87	size_t	cache_entries_size;
88
89	size_t	max_elemsize;		/* if 0 then no check is made */
90	size_t	satisf_elemsize;	/* if entry size is exceeded,
91					 * this number of elements will be left,
92					 * others will be deleted */
93	int	confidence_threshold;	/* number matching replies required */
94	struct timeval	max_lifetime;	/* if 0 then no check is made */
95	enum cache_policy_t policy;	/* policy used for transformations */
96};
97
98/* params, used for multipart entries */
99struct	mp_cache_entry_params {
100	struct cache_entry_params cep;
101
102	/* unique fields */
103	size_t	max_elemsize;	/* if 0 then no check is made */
104	size_t	max_sessions;	/* maximum number of active sessions */
105
106	struct timeval	max_lifetime;	/* maximum elements lifetime */
107};
108
109struct cache_ht_item_data_ {
110    	/* key is the bytes sequence only - not the null-terminated string */
111	char	*key;
112    	size_t	key_size;
113
114	char	*value;
115	size_t	value_size;
116
117	struct cache_policy_item_ *fifo_policy_item;
118	int	confidence;	/* incremented for each verification */
119};
120
121struct cache_ht_item_ {
122	HASHTABLE_ENTRY_HEAD(ht_item_, struct cache_ht_item_data_) data;
123};
124
125struct cache_entry_ {
126	char	*name;
127	struct cache_entry_params *params;
128};
129
130struct cache_common_entry_ {
131	char	*name;
132	struct cache_entry_params *params;
133
134	struct common_cache_entry_params common_params;
135
136	HASHTABLE_HEAD(cache_ht_, cache_ht_item_) items;
137	size_t items_size;
138
139	/*
140	 * Entry always has the FIFO policy, that is used to eliminate old
141	 * elements (the ones, with lifetime more than max_lifetime). Besides,
142	 * user can specify another policy to be applied, when there are too
143	 * many elements in the entry. So policies_size can be 1 or 2.
144	 */
145	struct cache_policy_ **policies;
146	size_t policies_size;
147
148	void	(*get_time_func)(struct timeval *);
149};
150
151struct cache_mp_data_item_ {
152	char	*value;
153	size_t	value_size;
154
155	TAILQ_ENTRY(cache_mp_data_item_) entries;
156};
157
158struct cache_mp_write_session_ {
159	struct cache_mp_entry_	*parent_entry;
160
161	/*
162	 * All items are accumulated in this queue. When the session is
163	 * committed, they all will be copied to the multipart entry.
164	 */
165	TAILQ_HEAD(cache_mp_data_item_head, cache_mp_data_item_) items;
166	size_t	items_size;
167
168	TAILQ_ENTRY(cache_mp_write_session_) entries;
169};
170
171struct cache_mp_read_session_ {
172	struct cache_mp_entry_ *parent_entry;
173	struct cache_mp_data_item_ *current_item;
174
175	TAILQ_ENTRY(cache_mp_read_session_) entries;
176};
177
178struct cache_mp_entry_ {
179	char	*name;
180	struct cache_entry_params *params;
181
182	struct mp_cache_entry_params mp_params;
183
184	/* All opened write sessions */
185	TAILQ_HEAD(write_sessions_head, cache_mp_write_session_) ws_head;
186	size_t	ws_size;
187
188	/* All opened read sessions */
189	TAILQ_HEAD(read_sessions_head, cache_mp_read_session_) rs_head;
190	size_t	rs_size;
191
192	/*
193	 * completed_write_session is the committed write sessions. All read
194	 * sessions use data from it. If the completed_write_session is out of
195	 * date, but still in use by some of the read sessions, the newly
196	 * committed write session is stored in the pending_write_session.
197	 * In such a case, completed_write_session will be substituted with
198	 * pending_write_session as soon as it won't be used by any of
199	 * the read sessions.
200	 */
201	struct cache_mp_write_session_	*completed_write_session;
202	struct cache_mp_write_session_	*pending_write_session;
203	struct timeval	creation_time;
204	struct timeval	last_request_time;
205
206	void	(*get_time_func)(struct timeval *);
207};
208
209struct cache_ {
210	struct cache_params params;
211
212	struct cache_entry_ **entries;
213	size_t	entries_capacity;
214	size_t	entries_size;
215};
216
217/* simple abstractions - for not to write "struct" every time */
218typedef struct cache_		*cache;
219typedef struct cache_entry_	*cache_entry;
220typedef struct cache_mp_write_session_	*cache_mp_write_session;
221typedef struct cache_mp_read_session_	*cache_mp_read_session;
222
223#define INVALID_CACHE		(NULL)
224#define INVALID_CACHE_ENTRY	(NULL)
225#define INVALID_CACHE_MP_WRITE_SESSION	(NULL)
226#define INVALID_CACHE_MP_READ_SESSION	(NULL)
227
228/*
229 * NOTE: all cache operations are thread-unsafe. You must ensure thread-safety
230 * externally, by yourself.
231 */
232
233/* cache initialization/destruction routines */
234cache init_cache(struct cache_params const *);
235void destroy_cache(cache);
236
237/* cache entries manipulation routines */
238int register_cache_entry(cache, struct cache_entry_params const *);
239int unregister_cache_entry(cache, const char *);
240cache_entry find_cache_entry(cache, const char *);
241
242/* read/write operations used on common entries */
243int cache_read(cache_entry, const char *, size_t, char *, size_t *);
244int cache_write(cache_entry, const char *, size_t, char const *, size_t);
245
246/* read/write operations used on multipart entries */
247cache_mp_write_session open_cache_mp_write_session(cache_entry);
248int cache_mp_write(cache_mp_write_session, char *, size_t);
249void abandon_cache_mp_write_session(cache_mp_write_session);
250void close_cache_mp_write_session(cache_mp_write_session);
251
252cache_mp_read_session open_cache_mp_read_session(cache_entry);
253int cache_mp_read(cache_mp_read_session, char *, size_t *);
254void close_cache_mp_read_session(cache_mp_read_session);
255
256/* transformation routines */
257int transform_cache_entry(cache_entry, enum cache_transformation_t);
258int transform_cache_entry_part(cache_entry, enum cache_transformation_t,
259	const char *, size_t, enum part_position_t);
260
261#endif
262