1# Cache Configuration of `wasmtime` 2 3The configuration file uses the [toml] format. 4You can create a configuration file at the default location with: 5```sh 6$ wasmtime config new 7``` 8It will print the location regardless of the success. 9Please refer to the `--help` message for using a custom location. 10 11All settings, except `enabled`, are **optional**. 12If the setting is not specified, the **default** value is used. 13***Thus, if you don't know what values to use, don't specify them.*** 14The default values might be tuned in the future. 15 16Wasmtime assumes all the options are in the `cache` section. 17 18Example config: 19```toml 20[cache] 21enabled = true 22directory = "/nfs-share/wasmtime-cache/" 23cleanup-interval = "30m" 24files-total-size-soft-limit = "1Gi" 25``` 26 27Please refer to the [cache system] section to learn how it works. 28 29If you think some default value should be tuned, some new settings 30should be introduced or some behavior should be changed, you are 31welcome to discuss it and contribute to [the Wasmtime repository]. 32 33[the Wasmtime repository]: https://github.com/bytecodealliance/wasmtime 34 35Setting `enabled` 36----------------- 37- **type**: boolean 38- **format**: `true | false` 39- **default**: `true` 40 41Specifies whether the cache system is used or not. 42 43This field is *mandatory*. 44The default value is used when configuration file is not specified 45and none exists at the default location. 46 47[`enabled`]: #setting-enabled 48 49Setting `directory` 50----------------- 51- **type**: string (path) 52- **default**: look up `cache_dir` in [directories] crate 53 54Specifies where the cache directory is. Must be an absolute path. 55 56[`directory`]: #setting-directory 57 58Setting `worker-event-queue-size` 59----------------- 60- **type**: string (SI prefix) 61- **format**: `"{integer}(K | M | G | T | P)?"` 62- **default**: `"16"` 63 64Size of [cache worker] event queue. 65If the queue is full, incoming cache usage events will be dropped. 66 67[`worker-event-queue-size`]: #setting-worker-event-queue-size 68 69Setting `baseline-compression-level` 70------------------ 71- **type**: integer 72- **default**: `3`, the default zstd compression level 73 74Compression level used when a new cache file is being written by the [cache system]. 75Wasmtime uses [zstd] compression. 76 77[`baseline-compression-level`]: #setting-baseline-compression-level 78 79Setting `optimized-compression-level` 80------------------ 81- **type**: integer 82- **default**: `20` 83 84Compression level used when the [cache worker] decides to recompress a cache file. 85Wasmtime uses [zstd] compression. 86 87[`optimized-compression-level`]: #setting-optimized-compression-level 88 89Setting `optimized-compression-usage-counter-threshold` 90------------------ 91- **type**: string (SI prefix) 92- **format**: `"{integer}(K | M | G | T | P)?"` 93- **default**: `"256"` 94 95One of the conditions for the [cache worker] to recompress a cache file 96is to have usage count of the file exceeding this threshold. 97 98[`optimized-compression-usage-counter-threshold`]: #setting-optimized-compression-usage-counter-threshold 99 100Setting `cleanup-interval` 101------------------ 102- **type**: string (duration) 103- **format**: `"{integer}(s | m | h | d)"` 104- **default**: `"1h"` 105 106When the [cache worker] is notified about a cache file being updated by the [cache system] 107and this interval has already passed since last cleaning up, 108the worker will attempt a new cleanup. 109 110Please also refer to [`allowed-clock-drift-for-files-from-future`]. 111 112[`cleanup-interval`]: #setting-cleanup-interval 113 114Setting `optimizing-compression-task-timeout` 115------------------ 116- **type**: string (duration) 117- **format**: `"{integer}(s | m | h | d)"` 118- **default**: `"30m"` 119 120When the [cache worker] decides to recompress a cache file, it makes sure that 121no other worker has started the task for this file within the last 122[`optimizing-compression-task-timeout`] interval. 123If some worker has started working on it, other workers are skipping this task. 124 125Please also refer to the [`allowed-clock-drift-for-files-from-future`] section. 126 127[`optimizing-compression-task-timeout`]: #setting-optimizing-compression-task-timeout 128 129Setting `allowed-clock-drift-for-files-from-future` 130------------------ 131- **type**: string (duration) 132- **format**: `"{integer}(s | m | h | d)"` 133- **default**: `"1d"` 134 135### Locks 136When the [cache worker] attempts acquiring a lock for some task, 137it checks if some other worker has already acquired such a lock. 138To be fault tolerant and eventually execute every task, 139the locks expire after some interval. 140However, because of clock drifts and different timezones, 141it would happen that some lock was created in the future. 142This setting defines a tolerance limit for these locks. 143If the time has been changed in the system (i.e. two years backwards), 144the [cache system] should still work properly. 145Thus, these locks will be treated as expired 146(assuming the tolerance is not too big). 147 148### Cache files 149Similarly to the locks, the cache files or their metadata might 150have modification time in distant future. 151The cache system tries to keep these files as long as possible. 152If the limits are not reached, the cache files will not be deleted. 153Otherwise, they will be treated as the oldest files, so they might survive. 154If the user actually uses the cache file, the modification time will be updated. 155 156[`allowed-clock-drift-for-files-from-future`]: #setting-allowed-clock-drift-for-files-from-future 157 158Setting `file-count-soft-limit` 159------------------ 160- **type**: string (SI prefix) 161- **format**: `"{integer}(K | M | G | T | P)?"` 162- **default**: `"65536"` 163 164Soft limit for the file count in the cache directory. 165 166This doesn't include files with metadata. 167To learn more, please refer to the [cache system] section. 168 169[`file-count-soft-limit`]: #setting-file-count-soft-limit 170 171Setting `files-total-size-soft-limit` 172------------------ 173- **type**: string (disk space) 174- **format**: `"{integer}(K | Ki | M | Mi | G | Gi | T | Ti | P | Pi)?"` 175- **default**: `"512Mi"` 176 177Soft limit for the total size* of files in the cache directory. 178 179This doesn't include files with metadata. 180To learn more, please refer to the [cache system] section. 181 182*this is the file size, not the space physically occupied on the disk. 183 184[`files-total-size-soft-limit`]: #setting-files-total-size-soft-limit 185 186Setting `file-count-limit-percent-if-deleting` 187------------------ 188- **type**: string (percent) 189- **format**: `"{integer}%"` 190- **default**: `"70%"` 191 192If [`file-count-soft-limit`] is exceeded and the [cache worker] performs the cleanup task, 193then the worker will delete some cache files, so after the task, 194the file count should not exceed 195[`file-count-soft-limit`] * [`file-count-limit-percent-if-deleting`]. 196 197This doesn't include files with metadata. 198To learn more, please refer to the [cache system] section. 199 200[`file-count-limit-percent-if-deleting`]: #setting-file-count-limit-percent-if-deleting 201 202Setting `files-total-size-limit-percent-if-deleting` 203------------------ 204- **type**: string (percent) 205- **format**: `"{integer}%"` 206- **default**: `"70%"` 207 208If [`files-total-size-soft-limit`] is exceeded and [cache worker] performs the cleanup task, 209then the worker will delete some cache files, so after the task, 210the files total size should not exceed 211[`files-total-size-soft-limit`] * [`files-total-size-limit-percent-if-deleting`]. 212 213This doesn't include files with metadata. 214To learn more, please refer to the [cache system] section. 215 216[`files-total-size-limit-percent-if-deleting`]: #setting-files-total-size-limit-percent-if-deleting 217 218[toml]: https://github.com/toml-lang/toml 219[directories]: https://crates.io/crates/directories 220[cache system]: #how-does-the-cache-work 221[cache worker]: #how-does-the-cache-work 222[zstd]: https://facebook.github.io/zstd/ 223[Least Recently Used (LRU)]: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU) 224 225How does the cache work? 226======================== 227 228**This is an implementation detail and might change in the future.** 229Information provided here is meant to help understanding the big picture 230and configuring the cache. 231 232There are two main components - the *cache system* and the *cache worker*. 233 234Cache system 235------------ 236 237Handles GET and UPDATE cache requests. 238- **GET request** - simply loads the cache from disk if it is there. 239- **UPDATE request** - compresses received data with [zstd] and [`baseline-compression-level`], then writes the data to the disk. 240 241In case of successful handling of a request, it notifies the *cache worker* about this 242event using the queue. 243The queue has a limited size of [`worker-event-queue-size`]. If it is full, it will drop 244new events until the *cache worker* pops some event from the queue. 245 246Cache worker 247------------ 248 249The cache worker runs in a single thread with lower priority and pops events from the queue 250in a loop handling them one by one. 251 252### On GET request 2531. Read the statistics file for the cache file, 254 increase the usage counter and write it back to the disk. 2552. Attempt recompressing the cache file if all of the following conditions are met: 256 - usage counter exceeds [`optimized-compression-usage-counter-threshold`], 257 - the file is compressed with compression level lower than [`optimized-compression-level`], 258 - no other worker has started working on this particular task within the last 259 [`optimizing-compression-task-timeout`] interval. 260 261 When recompressing, [`optimized-compression-level`] is used as a compression level. 262 263### On UPDATE request 2641. Write a fresh statistics file for the cache file. 2652. Clean up the cache if no worker has attempted to do this within the last [`cleanup-interval`]. 266 During this task: 267 - all unrecognized files and expired task locks in cache directory will be deleted 268 - if [`file-count-soft-limit`] or [`files-total-size-soft-limit`] is exceeded, 269 then recognized files will be deleted according to 270 [`file-count-limit-percent-if-deleting`] and [`files-total-size-limit-percent-if-deleting`]. 271 Wasmtime uses [Least Recently Used (LRU)] cache replacement policy and requires that 272 the filesystem maintains proper mtime (modification time) of the files. 273 Files with future mtimes are treated specially - more details 274 in [`allowed-clock-drift-for-files-from-future`]. 275 276### Metadata files 277- every cached WebAssembly module has its own statistics file 278- every lock is a file 279