1#ifndef AWS_COMMON_LRU_CACHE_H
2#define AWS_COMMON_LRU_CACHE_H
3/*
4 * Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License").
7 * You may not use this file except in compliance with the License.
8 * A copy of the License is located at
9 *
10 * http://aws.amazon.com/apache2.0
11 *
12 * or in the "license" file accompanying this file. This file is distributed
13 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
14 * express or implied. See the License for the specific language governing
15 * permissions and limitations under the License.
16 */
17
18#include <aws/common/hash_table.h>
19#include <aws/common/linked_list.h>
20
21/**
22 * Simple Least-recently-used cache using the standard lazy linked hash table
23 * implementation. (Yes the one that was the answer to that interview question
24 * that one time).
25 */
26struct aws_lru_cache {
27 struct aws_allocator *allocator;
28 struct aws_linked_list list;
29 struct aws_hash_table table;
30 aws_hash_callback_destroy_fn *user_on_value_destroy;
31 size_t max_items;
32};
33
34AWS_EXTERN_C_BEGIN
35
36/**
37 * Initializes the cache. Sets up the underlying hash table and linked list.
38 * Once `max_items` elements have been added, the least recently used item will
39 * be removed. For the other parameters, see aws/common/hash_table.h. Hash table
40 * semantics of these arguments are preserved.
41 */
42AWS_COMMON_API
43int aws_lru_cache_init(
44 struct aws_lru_cache *cache,
45 struct aws_allocator *allocator,
46 aws_hash_fn *hash_fn,
47 aws_hash_callback_eq_fn *equals_fn,
48 aws_hash_callback_destroy_fn *destroy_key_fn,
49 aws_hash_callback_destroy_fn *destroy_value_fn,
50 size_t max_items);
51
52/**
53 * Cleans up the cache. Elements in the cache will be evicted and cleanup
54 * callbacks will be invoked.
55 */
56AWS_COMMON_API
57void aws_lru_cache_clean_up(struct aws_lru_cache *cache);
58
59/**
60 * Finds element in the cache by key. If found, it will become most-recently
61 * used, *p_value will hold the stored value, and AWS_OP_SUCCESS will be
62 * returned. If not found, AWS_OP_SUCCESS will be returned and *p_value will be
63 * NULL.
64 *
65 * If any errors occur AWS_OP_ERR will be returned.
66 */
67AWS_COMMON_API
68int aws_lru_cache_find(struct aws_lru_cache *cache, const void *key, void **p_value);
69
70/**
71 * Puts `p_value` at `key`. If an element is already stored at `key` it will be replaced. Added item becomes
72 * most-recently used. If the cache is already full, the least-recently-used item will be removed.
73 */
74AWS_COMMON_API
75int aws_lru_cache_put(struct aws_lru_cache *cache, const void *key, void *p_value);
76
77/**
78 * Removes item at `key` from the cache.
79 */
80AWS_COMMON_API
81int aws_lru_cache_remove(struct aws_lru_cache *cache, const void *key);
82
83/**
84 * Clears all items from the cache.
85 */
86AWS_COMMON_API
87void aws_lru_cache_clear(struct aws_lru_cache *cache);
88
89/**
90 * Accesses the least-recently-used element, sets it to most-recently-used
91 * element, and returns the value.
92 */
93AWS_COMMON_API
94void *aws_lru_cache_use_lru_element(struct aws_lru_cache *cache);
95
96/**
97 * Accesses the most-recently-used element and returns its value.
98 */
99AWS_COMMON_API
100void *aws_lru_cache_get_mru_element(const struct aws_lru_cache *cache);
101
102/**
103 * Returns the number of elements in the cache.
104 */
105AWS_COMMON_API
106size_t aws_lru_cache_get_element_count(const struct aws_lru_cache *cache);
107
108AWS_EXTERN_C_END
109
110#endif /* AWS_COMMON_LRU_CACHE_H */
111