- Generated on Tue Aug 19 2025 01:24:03 for BRL-CAD by
1.9.8
|
BRL-CAD
|
Go to the source code of this file.
Data Structures | |
| struct | bu_cache |
| struct | bu_cache_item |
Macros | |
| #define | BU_CACHE_DEFAULT_DB_SIZE 4294967296 |
| #define | BU_CACHE_KEY_MAXLEN 511 |
Functions | |
| struct bu_cache * | bu_cache_open (const char *cache_db, int create, size_t max_cache_size) |
| int | bu_cache_close (struct bu_cache *c) |
| void | bu_cache_erase (const char *cache_db) |
| size_t | bu_cache_get (void **data, const char *key, struct bu_cache *c, struct bu_cache_txn **t) |
| void | bu_cache_get_done (struct bu_cache_txn **t) |
| size_t | bu_cache_write (void *data, size_t dsize, const char *key, struct bu_cache *c, struct bu_cache_txn **t) |
| int | bu_cache_write_commit (struct bu_cache *c, struct bu_cache_txn **t) |
| void | bu_cache_write_abort (struct bu_cache_txn **t) |
| void | bu_cache_clear (const char *key, struct bu_cache *c, struct bu_cache_txn **t) |
| int | bu_cache_keys (char ***keysv, struct bu_cache *c) |
Routines for managing and accessing a key/value data store.
NOTE: Data backend storage is NOT guaranteed by this API from one BRL-CAD version to the next. Older versions of libbu caches may use different internal storage than newer ones. Should a backend need to change, we will strive to maintain support for reading in the previous backend when the new one is released to allow for data migration. However, cache data is ultimately intended to be ephemeral and subject to regeneration - if the maintenance burden of backwards compatibilty becomes too high the decision will be made to drop support for reading older caches.
For data that is canonical and not able to be regenerated from other sources (such as geometry or user settings) bu_cache is not an appropriate storage mechanism.
Definition in file cache.h.
Opens the specified cache database from the BRL-CAD BU_DIR_CACHE folder. The cache_db string may contain a hierarchical path, but note that all paths will be interpreted as relative to the BU_DIR_CACHE location - no absolute paths can be specified.
If the create flag is non-zero, bu_cache_open will create the specified cache_db if it does not already exist.
A zero argument to max_cache_size will result in BU_CACHE_DEFAULT_DB_SIZE being used. The size limit is a limit for the current session, not a perminent upper limit on how large a given cache can grow.
returns the bu_cache structure on success, NULL on failure.
|
extern |
Closes the bu_cache and frees all associated memory. Will NOT close if bu_cache_write still has an active txn - in that case, calling code needs to call bu_cache_write_commit or bu_cache_write_abort before bu_cache_close will succeed. returns BRLCAD_ERROR if close was not successful, else BRLCAD_OK.
Erase the specified cache from disk. Any open instances of the cache should be closed before calling this function.
| size_t bu_cache_get | ( | void ** | data, |
| const char * | key, | ||
| struct bu_cache * | c, | ||
| struct bu_cache_txn ** | t | ||
| ) |
Retrieve data (read-only) from the cache using the specified key. User should call bu_cache_get_done once their use of data is complete.
Returns the size of the retrieved data. If t is non-NULL and empty, a transaction token is returned that can be reused in subsequent calls. If it is non-NULL and non-empty, bu_cache_get treats *t as the current transaction. Note that when reusing a txn, the caller MUST call bu_cache_get_done to finalize a transaction.
If t is NULL, the data returned in data must be freed by the caller.
| void bu_cache_get_done | ( | struct bu_cache_txn ** | t | ) |
Data retrieved using bu_cache_get is temporary if we are using transaction tokens - once the user is done either reading it or copying it, libbu needs to be told that the usage of the returned data is complete.
| size_t bu_cache_write | ( | void * | data, |
| size_t | dsize, | ||
| const char * | key, | ||
| struct bu_cache * | c, | ||
| struct bu_cache_txn ** | t | ||
| ) |
Assign data to the cache using the specified key.
If t is NULL, the write is handled immediately as a complete operation, and bu_cache_write immediately validates that the written data can be successfully read.
If t is non-NULL, the txn is not finalized and the calling code can queue up more write operations for eventual commit. This mode is MUCH more performant when lots of rapid writes are needed, but no per-write read-back validation is performed (since the write is not yet finalized.) This mode requires explicit management of when to finalize the operation for the database, and if the user wants to validate that reads successfully return the expected data they will need to do it themselves, but the speedup will almost always be worth it for any non-trivial data input. If an individual write DOES report failure (return size 0) in this mode, parent code should not try to continue writing - they should call bu_cache_write_abort immediately and handle the failure case, since the commit operation will also ultimately fail.
A cache may only have one active write txn at a time - this is enforced internally in the implementation, and a bu_cache_write will fail if it attempts to create a new write when one is already active.
| int bu_cache_write_commit | ( | struct bu_cache * | c, |
| struct bu_cache_txn ** | t | ||
| ) |
Like bu_cache_get_done for data retrieval, a series of write operations may be either committed or (if the parent code has changed its mind) aborted. t is the bu_cache_txn returned by bu_cache write's t parameter.
returns BRLCAD_OK on success and BRLCAD_ERROR on error.
| void bu_cache_write_abort | ( | struct bu_cache_txn ** | t | ) |
If the calling code decides not to commit a series of bu_cache_write calls staged with a non-NULL t param to a bu_cache_write, call bu_cache_write_abort to clear the decks.
| void bu_cache_clear | ( | const char * | key, |
| struct bu_cache * | c, | ||
| struct bu_cache_txn ** | t | ||
| ) |
Clear data associated with the specified key from the cache. Because this is a write operation as far as the database is concerned, it is treated the same way bu_cache_write operations are as far as txn behavior is concerned. If you have a batch bu_cache_write in progress and want to do a clear, the write txn should be provided to bu_cache_clear as well, and like other writes it will not be finalized until commit is called.
1.9.8