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 | */ |
26 | struct 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 | |
34 | AWS_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 | */ |
42 | AWS_COMMON_API |
43 | int 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 | */ |
56 | AWS_COMMON_API |
57 | void 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 | */ |
67 | AWS_COMMON_API |
68 | int 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 | */ |
74 | AWS_COMMON_API |
75 | int 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 | */ |
80 | AWS_COMMON_API |
81 | int aws_lru_cache_remove(struct aws_lru_cache *cache, const void *key); |
82 | |
83 | /** |
84 | * Clears all items from the cache. |
85 | */ |
86 | AWS_COMMON_API |
87 | void 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 | */ |
93 | AWS_COMMON_API |
94 | void *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 | */ |
99 | AWS_COMMON_API |
100 | void *aws_lru_cache_get_mru_element(const struct aws_lru_cache *cache); |
101 | |
102 | /** |
103 | * Returns the number of elements in the cache. |
104 | */ |
105 | AWS_COMMON_API |
106 | size_t aws_lru_cache_get_element_count(const struct aws_lru_cache *cache); |
107 | |
108 | AWS_EXTERN_C_END |
109 | |
110 | #endif /* AWS_COMMON_LRU_CACHE_H */ |
111 | |