DISK CACHE: a bounded cache of files keyed by content

Macros
#define	N_DISK_CACHE_NAME_LEN   32
	length of an entry's name before its extension: 128 bits in hexadecimal

Functions
void	n_disk_cache_close (N_DISK_CACHE **cache)
	Forget a cache.
const char *	n_disk_cache_dir (const N_DISK_CACHE *cache)
	The cache's directory, as it was opened.
int	n_disk_cache_expire (const N_DISK_CACHE *cache, int64_t max_age_seconds)
	Remove every entry unused for longer than an age.
int	n_disk_cache_get (const N_DISK_CACHE *cache, const void *key, size_t key_len, const char *ext, size_t max_len, unsigned char **data, size_t *len)
	Read an entry.
N_DISK_CACHE *	n_disk_cache_open (const char *dir)
	Use a directory as a cache.
int	n_disk_cache_path (const N_DISK_CACHE *cache, const void *key, size_t key_len, const char *ext, char *out, size_t out_len)
	The file an entry lives in, whether or not it exists.
int	n_disk_cache_prune (const N_DISK_CACHE *cache, uint64_t max_bytes)
	Remove least recently used entries until the rest fit a budget.
int	n_disk_cache_prune_group (const N_DISK_CACHE *const *caches, int count, uint64_t max_bytes)
	n_disk_cache_prune() over several caches that share one budget.
int	n_disk_cache_put (const N_DISK_CACHE *cache, const void *key, size_t key_len, const char *ext, const void *data, size_t len)
	Store an entry, replacing any under the same key and extension.
int	n_disk_cache_remove (const N_DISK_CACHE *cache, const void *key, size_t key_len, const char *ext)
	Remove one entry, for a caller that found it unreadable.
int	n_disk_cache_size (const N_DISK_CACHE *cache, uint64_t *total)
	How many bytes the cache's entries take.

Detailed Description

Macro Definition Documentation

N_DISK_CACHE_NAME_LEN

#define N_DISK_CACHE_NAME_LEN   32

length of an entry's name before its extension: 128 bits in hexadecimal

Examples

ex_disk_cache.c.

Definition at line 73 of file n_disk_cache.h.

Referenced by _n_dc_owned(), _n_dc_walk(), main(), n_disk_cache_open(), and n_disk_cache_path().

Function Documentation

n_disk_cache_close()

void n_disk_cache_close

(

N_DISK_CACHE **

cache

)

Forget a cache.

Its files stay on disk.

Parameters

cache

address of the handle; set to NULL. NULL, or a pointer to NULL, is a no-op.

Definition at line 302 of file n_disk_cache.c.

References Free.

Referenced by main().

Here is the caller graph for this function:

n_disk_cache_dir()

const char * n_disk_cache_dir

(

const N_DISK_CACHE *

cache

)

The cache's directory, as it was opened.

Parameters

cache

the cache.

Returns

a string owned by the cache, or "" for a NULL cache.

Definition at line 308 of file n_disk_cache.c.

References N_DISK_CACHE::dir.

Referenced by main().

Here is the caller graph for this function:

n_disk_cache_expire()

int n_disk_cache_expire	(	const N_DISK_CACHE *	cache,
		int64_t	max_age_seconds )

Remove every entry unused for longer than an age.

Parameters

cache	the cache. Must not be NULL.
max_age_seconds	how long an entry may go unused. 0 or less removes nothing.

Returns

how many entries were removed, or -1 when the directory cannot be read.

Definition at line 512 of file n_disk_cache.c.

References __n_assert, _n_dc_join(), _n_dc_remove(), _n_dc_walk(), N_DISK_CACHE::dir, LOG_DEBUG, N_DISK_CACHE_PATH_MAX, and n_log.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_get()

int n_disk_cache_get	(	const N_DISK_CACHE *	cache,
		const void *	key,
		size_t	key_len,
		const char *	ext,
		size_t	max_len,
		unsigned char **	data,
		size_t *	len )

Read an entry.

Parameters

cache	the cache. Must not be NULL.
key	the key's bytes. Must not be NULL.
key_len	how many bytes of key.
ext	the extension, as for n_disk_cache_path().
max_len	the largest entry accepted; a larger one is a miss.
data	receives a new buffer the caller frees with free(), one byte longer than the entry and NUL-terminated. Must not be NULL.
len	receives the entry's length. Must not be NULL.

Returns

TRUE on a hit, FALSE on a miss or an unreadable entry (then *data is NULL).

Definition at line 357 of file n_disk_cache.c.

References __n_assert, _n_dc_fopen(), key, n_disk_cache_path(), and N_DISK_CACHE_PATH_MAX.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_open()

N_DISK_CACHE * n_disk_cache_open

(

const char *

dir

)

Use a directory as a cache.

The directory must exist: making a nested one is the caller's (Allegro's al_make_directory(), or mkdir -p). Nothing in it is read or changed here.

Parameters

dir	the directory. Must not be NULL or empty.

Returns

a new cache owned by the caller, to release with n_disk_cache_close(), or NULL when dir is not a directory.

Definition at line 272 of file n_disk_cache.c.

References __n_assert, _n_dc_is_dir(), N_DISK_CACHE::dir, Free, LOG_ERR, Malloc, N_DISK_CACHE_NAME_LEN, N_DISK_CACHE_PATH_MAX, and n_log.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_path()

int n_disk_cache_path	(	const N_DISK_CACHE *	cache,
		const void *	key,
		size_t	key_len,
		const char *	ext,
		char *	out,
		size_t	out_len )

The file an entry lives in, whether or not it exists.

Parameters

cache	the cache. Must not be NULL.
key	the key's bytes. Must not be NULL.
key_len	how many bytes of key.
ext	appended to the name, with its dot, such as ".png". NULL or "" for none. Must not contain a path separator.
out	receives the path. Must not be NULL.
out_len	room in out.

Returns

TRUE, or FALSE on a bad argument or a path that does not fit.

Definition at line 312 of file n_disk_cache.c.

References __n_assert, _n_dc_join(), key, MurmurHash3_x64_128(), N_DISK_CACHE_NAME_LEN, and N_DISK_CACHE_SEED.

Referenced by has(), main(), n_disk_cache_get(), n_disk_cache_put(), n_disk_cache_remove(), and put_aged().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_prune()

int n_disk_cache_prune	(	const N_DISK_CACHE *	cache,
		uint64_t	max_bytes )

Remove least recently used entries until the rest fit a budget.

Sorted by the time each was last used, oldest first, and removed in that order: an exact LRU, not an approximation.

Parameters

cache	the cache. Must not be NULL.
max_bytes	the budget. 0 removes every entry.

Returns

how many entries were removed, or -1 when the directory cannot be read.

Definition at line 413 of file n_disk_cache.c.

References __n_assert, _n_dc_join(), _n_dc_older(), _n_dc_remove(), _n_dc_walk(), N_DISK_CACHE::dir, LOG_DEBUG, N_DISK_CACHE_PATH_MAX, n_log, and _N_DC_ENTRY::size.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_prune_group()

int n_disk_cache_prune_group	(	const N_DISK_CACHE *const *	caches,
		int	count,
		uint64_t	max_bytes )

n_disk_cache_prune() over several caches that share one budget.

Every entry of every cache in one list, sorted by the time each was last used, oldest first, and removed in that order until the total of all of them fits: one least recently used order across the directories, so a program that keeps two kinds of derived file apart still has one bound on the disk it takes, and neither kind is emptied first to spare the other.

Parameters

caches	the caches. Must not be NULL; a NULL entry is skipped.
count	how many, 1 or more.
max_bytes	the budget for all of them together. 0 removes every entry.

Returns

how many entries were removed, or -1 when a directory cannot be read, in which case nothing was removed.

Definition at line 452 of file n_disk_cache.c.

References __n_assert, _n_dc_group_older(), _n_dc_join(), _n_dc_remove(), _n_dc_walk(), _N_DC_GROUP_ENTRY::entry, LOG_DEBUG, N_DISK_CACHE_PATH_MAX, n_log, _N_DC_GROUP_ENTRY::owner, and _N_DC_ENTRY::size.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_put()

int n_disk_cache_put	(	const N_DISK_CACHE *	cache,
		const void *	key,
		size_t	key_len,
		const char *	ext,
		const void *	data,
		size_t	len )

Store an entry, replacing any under the same key and extension.

Written through n_file_write_atomic(): a reader never sees half an entry.

Parameters

cache	the cache. Must not be NULL.
key	the key's bytes. Must not be NULL.
key_len	how many bytes of key.
ext	the extension, as for n_disk_cache_path().
data	the entry. May be NULL when len is 0.
len	its length in bytes.

Returns

TRUE, or FALSE when it could not be written.

Definition at line 328 of file n_disk_cache.c.

References __n_assert, _n_dc_fopen(), _n_dc_remove(), _n_dc_replace(), key, LOG_DEBUG, n_disk_cache_path(), N_DISK_CACHE_PATH_MAX, and n_log.

Referenced by main(), and put_aged().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_remove()

int n_disk_cache_remove	(	const N_DISK_CACHE *	cache,
		const void *	key,
		size_t	key_len,
		const char *	ext )

Remove one entry, for a caller that found it unreadable.

Parameters

cache	the cache. Must not be NULL.
key	the key's bytes. Must not be NULL.
key_len	how many bytes of key.
ext	the extension, as for n_disk_cache_path().

Returns

TRUE when it is gone or was never there, FALSE when it could not be removed.

Definition at line 392 of file n_disk_cache.c.

References __n_assert, _n_dc_remove(), key, n_disk_cache_path(), and N_DISK_CACHE_PATH_MAX.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_disk_cache_size()

int n_disk_cache_size	(	const N_DISK_CACHE *	cache,
		uint64_t *	total )

How many bytes the cache's entries take.

Parameters

cache	the cache. Must not be NULL.
total	receives the sum of the entries' sizes. Must not be NULL.

Returns

how many entries there are, or -1 when the directory cannot be read.

Definition at line 400 of file n_disk_cache.c.

References __n_assert, and _n_dc_walk().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function: