{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1751771060, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"bbe36fbbb7792177fbf13fb9da38fc16", "oid":{ "oid": "014535d746087a4758c67a88dc99e632d0e3c085", "alias": [ "refs/heads/main"]},"blobname": "include/libwebsockets/lws-diskcache.h", "blob": "/*\n * libwebsockets - small server side websockets and web server implementation\n *\n * Copyright (C) 2010 - 2019 Andy Green \u003candy@warmcat.com\u003e\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \u0022Software\u0022), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \u0022AS IS\u0022, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\n/*! \u005cdefgroup diskcache LWS disk cache\n * ## Disk cache API\n *\n * Lws provides helper apis useful if you need a disk cache containing hashed\n * files and need to delete files from it on an LRU basis to keep it below some\n * size limit.\n *\n * The API `lws_diskcache_prepare()` deals with creating the cache dir and\n * 256 subdirs, which are used according to the first two chars of the hex\n * hash of the cache file.\n *\n * `lws_diskcache_create()` and `lws_diskcache_destroy()` allocate and free\n * an opaque struct that represents the disk cache.\n *\n * `lws_diskcache_trim()` should be called at eg, 1s intervals to perform the\n * cache dir monitoring and LRU autodelete in the background lazily. It can\n * be done in its own thread or on a timer... it monitors the directories in a\n * stateful way that stats one or more file in the cache per call, and keeps\n * a list of the oldest files as it goes. When it completes a scan, if the\n * aggregate size is over the limit, it will delete oldest files first to try\n * to keep it under the limit.\n *\n * The cache size monitoring is extremely efficient in time and memory even when\n * the cache directory becomes huge.\n *\n * `lws_diskcache_query()` is used to determine if the file already exists in\n * the cache, or if it must be created. If it must be created, then the file\n * is opened using a temp name that must be converted to a findable name with\n * `lws_diskcache_finalize_name()` when the generation of the file contents are\n * complete. Aborted cached files that did not complete generation will be\n * flushed by the LRU eventually. If the file already exists, it is 'touched'\n * to make it new again and the fd returned.\n *\n */\n///@{\n\nstruct lws_diskcache_scan;\n\n/**\n * lws_diskcache_create() - creates an opaque struct representing the disk cache\n *\n * \u005cparam cache_dir_base: The cache dir path, eg `/var/cache/mycache`\n * \u005cparam cache_size_limit: maximum size on disk the cache is allowed to use\n *\n * This returns an opaque `struct lws_diskcache_scan *` which represents the\n * disk cache, the trim scanning state and so on. You should use\n * `lws_diskcache_destroy()` to free it to destroy it.\n */\nLWS_VISIBLE LWS_EXTERN struct lws_diskcache_scan *\nlws_diskcache_create(const char *cache_dir_base, uint64_t cache_size_limit);\n\n/**\n * lws_diskcache_destroy() - destroys the pointer returned by ...create()\n *\n * \u005cparam lds: pointer to the pointer returned by lws_diskcache_create()\n *\n * Frees *lds and any allocations it did, and then sets *lds to NULL and\n * returns.\n */\nLWS_VISIBLE LWS_EXTERN void\nlws_diskcache_destroy(struct lws_diskcache_scan **lds);\n\n/**\n * lws_diskcache_prepare() - ensures the cache dir structure exists on disk\n *\n * \u005cparam cache_base_dir: The cache dir path, eg `/var/cache/mycache`\n * \u005cparam mode: octal dir mode to enforce, like 0700\n * \u005cparam uid: uid the cache dir should belong to\n *\n * This should be called while your app is still privileged. It will create\n * the cache directory structure on disk as necessary, enforce the given access\n * mode on it and set the given uid as the owner. It won't make any trouble\n * if the cache already exists.\n *\n * Typically the mode is 0700 and the owner is the user that your application\n * will transition to use when it drops root privileges.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_diskcache_prepare(const char *cache_base_dir, int mode, uid_t uid);\n\n#define LWS_DISKCACHE_QUERY_NO_CACHE\t0\n#define LWS_DISKCACHE_QUERY_EXISTS\t1\n#define LWS_DISKCACHE_QUERY_CREATING\t2\n#define LWS_DISKCACHE_QUERY_ONGOING\t3 /* something else is creating it */\n\n/**\n * lws_diskcache_query() - ensures the cache dir structure exists on disk\n *\n * \u005cparam lds: The opaque struct representing the disk cache\n * \u005cparam is_bot: nonzero means the request is from a bot. Don't create new cache contents if so.\n * \u005cparam hash_hex: hex string representation of the cache object hash\n * \u005cparam _fd: pointer to the fd to be set\n * \u005cparam cache: destination string to take the cache filepath\n * \u005cparam cache_len: length of the buffer at `cache`\n * \u005cparam extant_cache_len: pointer to a size_t to take any extant cached file size\n *\n * This function is called when you want to find if the hashed name already\n * exists in the cache. The possibilities for the return value are\n *\n * - LWS_DISKCACHE_QUERY_NO_CACHE: It's not in the cache and you can't create\n * it in the cache for whatever reason.\n * - LWS_DISKCACHE_QUERY_EXISTS: It exists in the cache. It's open RDONLY and\n * *_fd has been set to the file descriptor. *extant_cache_len has been set\n * to the size of the cached file in bytes. cache has been set to the\n * full filepath of the cached file. Closing _fd is your responsibility.\n * - LWS_DISKCACHE_QUERY_CREATING: It didn't exist, but a temp file has been\n * created in the cache and *_fd set to a file descriptor opened on it RDWR.\n * You should create the contents, and call `lws_diskcache_finalize_name()`\n * when it is done. Closing _fd is your responsibility.\n * - LWS_DISKCACHE_QUERY_ONGOING: not returned by this api, but you may find it\n * desirable to make a wrapper function which can handle another asynchronous\n * process that is already creating the cached file. This can be used to\n * indicate that situation externally... how to determine the same thing is\n * already being generated is out of scope of this api.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_diskcache_query(struct lws_diskcache_scan *lds, int is_bot,\n\t\t const char *hash_hex, int *_fd, char *cache, int cache_len,\n\t\t size_t *extant_cache_len);\n\n/**\n * lws_diskcache_query() - ensures the cache dir structure exists on disk\n *\n * \u005cparam cache: The cache file temp name returned with LWS_DISKCACHE_QUERY_CREATING\n *\n * This renames the cache file you are creating to its final name. It should\n * be called on the temp name returned by `lws_diskcache_query()` if it gave a\n * LWS_DISKCACHE_QUERY_CREATING return, after you have filled the cache file and\n * closed it.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_diskcache_finalize_name(char *cache);\n\n/**\n * lws_diskcache_trim() - performs one or more file checks in the cache for size management\n *\n * \u005cparam lds: The opaque object representing the cache\n *\n * This should be called periodically to statefully walk the cache on disk\n * collecting the oldest files. When it has visited every file, if the cache\n * is oversize it will delete the oldest files until it's back under size again.\n *\n * Each time it's called, it will look at one or more dir in the cache. If\n * called when the cache is oversize, it increases the amount of work done each\n * call until it is reduced again. Typically it will take 256 calls before it\n * deletes anything, so if called once per second, it will delete files once\n * every 4 minutes. Each call is very inexpensive both in memory and time.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_diskcache_trim(struct lws_diskcache_scan *lds);\n\n\n/**\n * lws_diskcache_secs_to_idle() - see how long to idle before calling trim\n *\n * \u005cparam lds: The opaque object representing the cache\n *\n * If the cache is undersize, there's no need to monitor it immediately. This\n * suggests how long to \u0022sleep\u0022 before calling `lws_diskcache_trim()` again.\n */\nLWS_VISIBLE LWS_EXTERN int\nlws_diskcache_secs_to_idle(struct lws_diskcache_scan *lds);\n///@}\n","s":{"c":1751771060,"u": 652}} ],"g": 4310,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}