/*- * Copyright (c) 2005 Michael Bushkov <bushman@rsu.ru> * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. */ #ifndef __NSCD_CACHELIB_H__ #define __NSCD_CACHELIB_H__ #include "hashtable.h" #include "cacheplcs.h" enum cache_entry_t { CET_COMMON = 0, /* cache item is atomic */ CET_MULTIPART /* cache item is formed part by part */ }; enum cache_transformation_t { CTT_FLUSH = 0, /* flush the cache - delete all obsolete items */ CTT_CLEAR = 1 /* delete all items in the cache */ }; /* cache deletion policy type enum */ enum cache_policy_t { CPT_FIFO = 0, /* first-in first-out */ CPT_LRU = 1, /* least recently used */ CPT_LFU = 2 /* least frequently used */ }; /* multipart sessions can be used for reading and writing */ enum cache_mp_session_t { CMPT_READ_SESSION, CMPT_WRITE_SESSION }; /* * When doing partial transformations of entries (which are applied for * elements with keys, that contain specified buffer in its left or * right part), this enum will show the needed position of the key part. */ enum part_position_t { KPPT_LEFT, KPPT_RIGHT }; /* num_levels attribute is obsolete, i think - user can always emulate it * by using one entry. * get_time_func is needed to have the clocks-independent counter */ struct cache_params { void (*get_time_func)(struct timeval *); }; /* * base structure - normal_cache_entry_params and multipart_cache_entry_params * are "inherited" from it */ struct cache_entry_params { enum cache_entry_t entry_type; char *entry_name; }; /* params, used for most entries */ struct common_cache_entry_params { struct cache_entry_params cep; size_t cache_entries_size; size_t max_elemsize; /* if 0 then no check is made */ size_t satisf_elemsize; /* if entry size is exceeded, * this number of elements will be left, * others will be deleted */ int confidence_threshold; /* number matching replies required */ struct timeval max_lifetime; /* if 0 then no check is made */ enum cache_policy_t policy; /* policy used for transformations */ }; /* params, used for multipart entries */ struct mp_cache_entry_params { struct cache_entry_params cep; /* unique fields */ size_t max_elemsize; /* if 0 then no check is made */ size_t max_sessions; /* maximum number of active sessions */ struct timeval max_lifetime; /* maximum elements lifetime */ }; struct cache_ht_item_data_ { /* key is the bytes sequence only - not the null-terminated string */ char *key; size_t key_size; char *value; size_t value_size; struct cache_policy_item_ *fifo_policy_item; int confidence; /* incremented for each verification */ }; struct cache_ht_item_ { HASHTABLE_ENTRY_HEAD(ht_item_, struct cache_ht_item_data_) data; }; struct cache_entry_ { char *name; struct cache_entry_params *params; }; struct cache_common_entry_ { char *name; struct cache_entry_params *params; struct common_cache_entry_params common_params; HASHTABLE_HEAD(cache_ht_, cache_ht_item_) items; size_t items_size; /* * Entry always has the FIFO policy, that is used to eliminate old * elements (the ones, with lifetime more than max_lifetime). Besides, * user can specify another policy to be applied, when there are too * many elements in the entry. So policies_size can be 1 or 2. */ struct cache_policy_ **policies; size_t policies_size; void (*get_time_func)(struct timeval *); }; struct cache_mp_data_item_ { char *value; size_t value_size; TAILQ_ENTRY(cache_mp_data_item_) entries; }; struct cache_mp_write_session_ { struct cache_mp_entry_ *parent_entry; /* * All items are accumulated in this queue. When the session is * committed, they all will be copied to the multipart entry. */ TAILQ_HEAD(cache_mp_data_item_head, cache_mp_data_item_) items; size_t items_size; TAILQ_ENTRY(cache_mp_write_session_) entries; }; struct cache_mp_read_session_ { struct cache_mp_entry_ *parent_entry; struct cache_mp_data_item_ *current_item; TAILQ_ENTRY(cache_mp_read_session_) entries; }; struct cache_mp_entry_ { char *name; struct cache_entry_params *params; struct mp_cache_entry_params mp_params; /* All opened write sessions */ TAILQ_HEAD(write_sessions_head, cache_mp_write_session_) ws_head; size_t ws_size; /* All opened read sessions */ TAILQ_HEAD(read_sessions_head, cache_mp_read_session_) rs_head; size_t rs_size; /* * completed_write_session is the committed write sessions. All read * sessions use data from it. If the completed_write_session is out of * date, but still in use by some of the read sessions, the newly * committed write session is stored in the pending_write_session. * In such a case, completed_write_session will be substituted with * pending_write_session as soon as it won't be used by any of * the read sessions. */ struct cache_mp_write_session_ *completed_write_session; struct cache_mp_write_session_ *pending_write_session; struct timeval creation_time; struct timeval last_request_time; void (*get_time_func)(struct timeval *); }; struct cache_ { struct cache_params params; struct cache_entry_ **entries; size_t entries_capacity; size_t entries_size; }; /* simple abstractions - for not to write "struct" every time */ typedef struct cache_ *cache; typedef struct cache_entry_ *cache_entry; typedef struct cache_mp_write_session_ *cache_mp_write_session; typedef struct cache_mp_read_session_ *cache_mp_read_session; #define INVALID_CACHE (NULL) #define INVALID_CACHE_ENTRY (NULL) #define INVALID_CACHE_MP_WRITE_SESSION (NULL) #define INVALID_CACHE_MP_READ_SESSION (NULL) /* * NOTE: all cache operations are thread-unsafe. You must ensure thread-safety * externally, by yourself. */ /* cache initialization/destruction routines */ cache init_cache(struct cache_params const *); void destroy_cache(cache); /* cache entries manipulation routines */ int register_cache_entry(cache, struct cache_entry_params const *); int unregister_cache_entry(cache, const char *); cache_entry find_cache_entry(cache, const char *); /* read/write operations used on common entries */ int cache_read(cache_entry, const char *, size_t, char *, size_t *); int cache_write(cache_entry, const char *, size_t, char const *, size_t); /* read/write operations used on multipart entries */ cache_mp_write_session open_cache_mp_write_session(cache_entry); int cache_mp_write(cache_mp_write_session, char *, size_t); void abandon_cache_mp_write_session(cache_mp_write_session); void close_cache_mp_write_session(cache_mp_write_session); cache_mp_read_session open_cache_mp_read_session(cache_entry); int cache_mp_read(cache_mp_read_session, char *, size_t *); void close_cache_mp_read_session(cache_mp_read_session); /* transformation routines */ int transform_cache_entry(cache_entry, enum cache_transformation_t); int transform_cache_entry_part(cache_entry, enum cache_transformation_t, const char *, size_t, enum part_position_t); #endif
