Timeout Cache (tcache)

The tcache implements a simple component for caching data structures that can be referenced by unique, opaque keys. More...

Files
file	tcache.c
file	tcache.h
Data Structures
struct	PINT_tcache
	Describes a tcache instance. More...
struct	PINT_tcache_entry
	Describes a single entry in the tcache. More...
Enumerations
enum	PINT_tcache_replace_algorithms { LEAST_RECENTLY_USED = 1 }
enum	PINT_tcache_options {   TCACHE_TIMEOUT_MSECS = 1, TCACHE_NUM_ENTRIES = 2, TCACHE_HARD_LIMIT = 3, TCACHE_SOFT_LIMIT = 4,   TCACHE_ENABLE = 5, TCACHE_RECLAIM_PERCENTAGE = 6, TCACHE_REPLACE_ALGORITHM = 7, TCACHE_ENABLE_EXPIRATION = 8 }
Functions
PINT_tcache *	PINT_tcache_initialize (int(*compare_key_entry)(void *key, struct qhash_head *link), int(*hash_key)(void *key, int table_size), int(*free_payload)(void *payload), int table_size)
void	PINT_tcache_finalize (struct PINT_tcache *tcache)
int	PINT_tcache_get_info (struct PINT_tcache *tcache, enum PINT_tcache_options option, unsigned int *arg)
int	PINT_tcache_set_info (struct PINT_tcache *tcache, enum PINT_tcache_options option, unsigned int arg)
int	PINT_tcache_insert_entry (struct PINT_tcache *tcache, void *key, void *payload, int *purged)
int	PINT_tcache_lookup (struct PINT_tcache *tcache, void *key, struct PINT_tcache_entry **entry, int *status)
int	PINT_tcache_reclaim (struct PINT_tcache *tcache, int *reclaimed)
int	PINT_tcache_delete (struct PINT_tcache *tcache, struct PINT_tcache_entry *entry)
int	PINT_tcache_refresh_entry (struct PINT_tcache *tcache, struct PINT_tcache_entry *entry)

---

Detailed Description

The tcache implements a simple component for caching data structures that can be referenced by unique, opaque keys.

A timeout is associated with each entry to dictate when it will expire. Specific caches such as the attribute or name cache may be built on top of this one.

Notes:

• This interface is not thread safe. Caller must provided any necessary protection against race conditions.
• Also note that keys should be considered immutable once an item is inserted into the cache.
• The caller is responsible for allocating memory for payloads and for copying the payload if the information needs to be kept after a lookup. However, the tcache is responsible for freeing the payload.

Terminology:

• DELETE: Process of removing a specific entry at the request of the caller
• PURGE: Process of removing an entry because there is not enough room in the cache (see RECLAIM)
• EXPIRED: CACHE entry that is older than CACHE_TIMEOUT_MSECS and is still in the CACHE
• RECLAIM: Process of purging up to CACHE_RECLAIM_PERCENTAGE entries from the CACHE that are EXPIRED
• REFRESH: Process of updating an existing entry in cache with a new CACHE_TIMEOUT_MSECS

Policies:

• Cached items become EXPIRED after CACHE_TIMEOUT_MSECS from the time of insertion. Expiration can be turned off if cache entries don't decay by setting TCACHE_ENABLE_EXPIRATION to 0.
• CACHE_SOFT_LIMIT defined how many entries must exist before a RECLAIM of cached entries is attempted
• CACHE_RECLAIM_PERCENTAGE specifies the maximum number of entries in the cache that will be PURGED on a single pass. The max number of entries will be calculated as "CACHE_RECLAIM_PERCENTAGE/100 * SOFT_LIMIT"
• CACHE_HARD_LIMIT will specify the maximum number of entries that can exist in the cache.
• Once CACHE_HARD_LIMIT is reached, an item that needs to be cached will replace the least recently used item in the cache.
• To turn OFF caching, set the CACHE_TIMEOUT_MSECS to 0 or set the "enable" option to 0
• keys and data cached are void * types
• must be provided comparison function to search for cache entries
• must be provided hash function to index cache entries

---

Enumeration Type Documentation

enum PINT_tcache_options

enumeration of options to get_info() and set_info() calls See also: PINT_tcache_get_info() PINT_tcache_set_info() Enumeration values: TCACHE_TIMEOUT_MSECS  get/set tcache timeout value TCACHE_NUM_ENTRIES  get number of entries (not setable) TCACHE_HARD_LIMIT  get/set hard limit TCACHE_SOFT_LIMIT  get/set soft limit TCACHE_ENABLE  enable/disable tcache TCACHE_RECLAIM_PERCENTAGE  get/set reclaim percentage TCACHE_REPLACE_ALGORITHM  determines algorithm to use to find an entry to replace TCACHE_ENABLE_EXPIRATION  turn on/off expiration

enum PINT_tcache_replace_algorithms

enumeration for algorithms to use to determine how to search the tcache to find an entry to be replaced. See also: PINT_tcache_options Enumeration values: LEAST_RECENTLY_USED  find the least recently used entry

---

Function Documentation

int PINT_tcache_delete (  struct PINT_tcache *  tcache, struct PINT_tcache_entry *  entry )

Removes and destroys specified tcache entry. The payload_free() function will be used to destroy payload data. Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance entry  entry to remove and destroy

void PINT_tcache_finalize (  struct PINT_tcache *  tcache  )

Finalizes and destroys a tcache instance, frees all payloads. Parameters: tcache  tcache instance to destroy

Here is the call graph for this function:

int PINT_tcache_get_info (  struct PINT_tcache *  tcache, enum PINT_tcache_options  option, unsigned int *  arg )

Retrieves parameters from a tcache instance. See also: PINT_tcache_options Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance option  option to read arg  output value

struct PINT_tcache* PINT_tcache_initialize (  int(*  compare_key_entry)(void *key, struct qhash_head *link), int(*  hash_key)(void *key, int table_size), int(*  free_payload)(void *payload), int  table_size )

Initializes a tcache instance. Returns: pointer to tcache on success, NULL on failure Parameters: compare_key_entry  function to compare keys with payloads within entry, return 1 on match, 0 if not match hash_key  function to hash keys free_payload  function to free payload members (used during reclaim) table_size  size of hash table to use

int PINT_tcache_insert_entry (  struct PINT_tcache *  tcache, void *  key, void *  payload, int *  purged )

Adds an entry to the tcache. Caller must not retain a pointer to the payload; it could be destroyed at any time. Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance key  that uniquely identifies the payload payload  data to store in the cache purged  number of entries purged to make room

Here is the call graph for this function:

int PINT_tcache_lookup (  struct PINT_tcache *  tcache, void *  key, struct PINT_tcache_entry **  entry, int *  status )

Looks up an entry. Subsequent tcache function calls may destroy the entry and payload. Therefore the caller should copy the payload data if it intends to use it after another tcache function call. Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance key  that uniquely identifies the payload entry  tcache entry (output) status  indicates if the entry is expired or not

Here is the call graph for this function:

int PINT_tcache_reclaim (  struct PINT_tcache *  tcache, int *  reclaimed )

Tries to purge and destroy expired entries, up to TCACHE_RECLAIM_PERCENTAGE of the current soft limit value. The payload_free() function is used to destroy the payload associated with reclaimed entries. Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance reclaimed  number of entries reclaimed

Here is the call graph for this function:

int PINT_tcache_refresh_entry (  struct PINT_tcache *  tcache, struct PINT_tcache_entry *  entry )

Updates the timestamp on the specified entry to TCACHE_TIMEOUT milliseconds in the future. Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance entry  entry to refresh

int PINT_tcache_set_info (  struct PINT_tcache *  tcache, enum PINT_tcache_options  option, unsigned int  arg )

Sets optional parameters on a tcache instance. See also: PINT_tcache_options Returns: 0 on success, -PVFS_error on failure Parameters: tcache  pointer to tcache instance option  option to modify arg  input value

---