1 /** 2 * @file lv_cache_private.h 3 * 4 */ 5 6 #ifndef LV_CACHE_PRIVATE_H 7 #define LV_CACHE_PRIVATE_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "../lv_types.h" 17 #include "../../osal/lv_os.h" 18 19 /********************* 20 * DEFINES 21 *********************/ 22 23 /********************** 24 * TYPEDEFS 25 **********************/ 26 27 /** 28 * The result of the cache reserve condition callback 29 */ 30 typedef enum { 31 LV_CACHE_RESERVE_COND_OK, /**< The condition is met and no entries need to be evicted */ 32 LV_CACHE_RESERVE_COND_TOO_LARGE, /**< The condition is not met and the reserve size is too large */ 33 LV_CACHE_RESERVE_COND_NEED_VICTIM, /**< The condition is not met and a victim is needed to be evicted */ 34 LV_CACHE_RESERVE_COND_ERROR /**< An error occurred while checking the condition */ 35 } lv_cache_reserve_cond_res_t; 36 37 struct _lv_cache_ops_t; 38 struct _lv_cache_t; 39 struct _lv_cache_class_t; 40 struct _lv_cache_entry_t; 41 42 typedef struct _lv_cache_ops_t lv_cache_ops_t; 43 typedef struct _lv_cache_class_t lv_cache_class_t; 44 45 typedef int8_t lv_cache_compare_res_t; 46 typedef bool (*lv_cache_create_cb_t)(void * node, void * user_data); 47 typedef void (*lv_cache_free_cb_t)(void * node, void * user_data); 48 typedef lv_cache_compare_res_t (*lv_cache_compare_cb_t)(const void * a, const void * b); 49 50 /** 51 * The cache instance allocation function, used by the cache class to allocate memory for cache instances. 52 * @return It should return a pointer to the allocated instance. 53 */ 54 typedef void * (*lv_cache_alloc_cb_t)(void); 55 56 /** 57 * The cache instance initialization function, used by the cache class to initialize the cache instance. 58 * @return It should return true if the initialization is successful, false otherwise. 59 */ 60 typedef bool (*lv_cache_init_cb_t)(lv_cache_t * cache); 61 62 /** 63 * The cache instance destruction function, used by the cache class to destroy the cache instance. 64 */ 65 typedef void (*lv_cache_destroy_cb_t)(lv_cache_t * cache, void * user_data); 66 67 /** 68 * The cache get function, used by the cache class to get a cache entry by its key. 69 * @return `NULL` if the key is not found. 70 */ 71 typedef lv_cache_entry_t * (*lv_cache_get_cb_t)(lv_cache_t * cache, const void * key, void * user_data); 72 73 /** 74 * The cache add function, used by the cache class to add a cache entry with a given key. 75 * This function only cares about how to add the entry, it doesn't check if the entry already exists and doesn't care about is it a victim or not. 76 * @return the added cache entry, or NULL if the entry is not added. 77 */ 78 typedef lv_cache_entry_t * (*lv_cache_add_cb_t)(lv_cache_t * cache, const void * key, void * user_data); 79 80 /** 81 * The cache remove function, used by the cache class to remove a cache entry from the cache but doesn't free the memory.. 82 * This function only cares about how to remove the entry, it doesn't care about is it a victim or not. 83 */ 84 typedef void (*lv_cache_remove_cb_t)(lv_cache_t * cache, lv_cache_entry_t * entry, void * user_data); 85 86 /** 87 * The cache drop function, used by the cache class to remove a cache entry from the cache and free the memory. 88 */ 89 typedef void (*lv_cache_drop_cb_t)(lv_cache_t * cache, const void * key, void * user_data); 90 91 /** 92 * The cache drop all function, used by the cache class to remove all cache entries from the cache and free the memory. 93 */ 94 typedef void (*lv_cache_drop_all_cb_t)(lv_cache_t * cache, void * user_data); 95 96 /** 97 * The cache get victim function, used by the cache class to get a victim entry to be evicted. 98 */ 99 typedef lv_cache_entry_t * (*lv_cache_get_victim_cb)(lv_cache_t * cache, void * user_data); 100 101 /** 102 * The cache reserve condition function, used by the cache class to check if a new entry can be added to the cache without exceeding its maximum size. 103 * See lv_cache_reserve_cond_res_t for the possible results. 104 */ 105 typedef lv_cache_reserve_cond_res_t (*lv_cache_reserve_cond_cb)(lv_cache_t * cache, const void * key, size_t size, 106 void * user_data); 107 108 /** 109 * The cache iterator creation function, used by the cache class to create an iterator for the cache. 110 * @return A pointer to the created iterator, or NULL if the iterator cannot be created. 111 */ 112 typedef lv_iter_t * (*lv_cache_iter_create_cb)(lv_cache_t * cache); 113 114 /** 115 * The cache operations struct 116 */ 117 struct _lv_cache_ops_t { 118 lv_cache_compare_cb_t compare_cb; /**< Compare function for keys */ 119 lv_cache_create_cb_t create_cb; /**< Create function for nodes */ 120 lv_cache_free_cb_t free_cb; /**< Free function for nodes */ 121 }; 122 123 /** 124 * The cache entry struct 125 */ 126 struct _lv_cache_t { 127 const lv_cache_class_t * clz; /**< Cache class. There are two built-in classes: 128 * - lv_cache_class_lru_rb_count for LRU-based cache with count-based eviction policy. 129 * - lv_cache_class_lru_rb_size for LRU-based cache with size-based eviction policy. */ 130 131 uint32_t node_size; /**< Size of a node */ 132 133 uint32_t max_size; /**< Maximum size of the cache */ 134 uint32_t size; /**< Current size of the cache */ 135 136 lv_cache_ops_t ops; /**< Cache operations struct _lv_cache_ops_t */ 137 138 lv_mutex_t lock; /**< Cache lock used to protect the cache in multithreading environments */ 139 140 const char * name; /**< Name of the cache */ 141 }; 142 143 /** 144 * Cache class struct for building custom cache classes 145 * 146 * Examples: 147 * - lv_cache_class_lru_rb_count for LRU-based cache with count-based eviction policy. 148 * - lv_cache_class_lru_rb_size for LRU-based cache with size-based eviction policy. 149 */ 150 struct _lv_cache_class_t { 151 lv_cache_alloc_cb_t alloc_cb; /**< The allocation function for cache entries */ 152 lv_cache_init_cb_t init_cb; /**< The initialization function for cache entries */ 153 lv_cache_destroy_cb_t destroy_cb; /**< The destruction function for cache entries */ 154 155 lv_cache_get_cb_t get_cb; /**< The get function for cache entries */ 156 lv_cache_add_cb_t add_cb; /**< The add function for cache entries */ 157 lv_cache_remove_cb_t remove_cb; /**< The remove function for cache entries */ 158 lv_cache_drop_cb_t drop_cb; /**< The drop function for cache entries */ 159 lv_cache_drop_all_cb_t drop_all_cb; /**< The drop all function for cache entries */ 160 lv_cache_get_victim_cb get_victim_cb; /**< The get victim function for cache entries */ 161 lv_cache_reserve_cond_cb reserve_cond_cb; /**< The reserve condition function for cache entries */ 162 163 lv_cache_iter_create_cb iter_create_cb; /**< The iterator creation function for cache entries */ 164 }; 165 166 /*----------------- 167 * Cache entry slot 168 *----------------*/ 169 170 struct _lv_cache_slot_size_t; 171 172 typedef struct _lv_cache_slot_size_t lv_cache_slot_size_t; 173 174 /** 175 * Cache entry slot struct 176 * 177 * To add new fields to the cache entry, add them to a new struct and add it to the first 178 * field of the cache data struct. And this one is a size slot for the cache entry. 179 */ 180 struct _lv_cache_slot_size_t { 181 size_t size; 182 }; 183 /********************** 184 * GLOBAL PROTOTYPES 185 **********************/ 186 187 /************************* 188 * GLOBAL VARIABLES 189 *************************/ 190 191 /********************** 192 * MACROS 193 **********************/ 194 195 #ifdef __cplusplus 196 } /*extern "C"*/ 197 #endif 198 199 #endif /*LV_CACHE_PRIVATE_H*/ 200
