[Mesa-dev] [PATCH 1/7] glsl: Add cache.h, defining an API for a persistent cache of objects

[Carl Worth]

This API forms the base infrastructure for the future shader cache. At
this point, the cache is simply a persistent, on-disk store of objects
stored and retrieved by 20-byte keys.
---
 src/glsl/cache.h | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 src/glsl/cache.h

diff --git a/src/glsl/cache.h b/src/glsl/cache.h
new file mode 100644
index 0000000..5e9b3a8
--- /dev/null
+++ b/src/glsl/cache.h
@@ -0,0 +1,121 @@
+/*
+ * Copyright © 2014 Intel Corporation
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+#pragma once
+#ifndef CACHE_H
+#define CACHE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+/* These functions implement a persistent, (on disk), cache of objects.
+ *
+ * Objects are stored and retrieved from the cache using keys which are each a
+ * sequence of 20 arbitrary bytes. This 20-byte size is chosen to allow for a
+ * SHA-1 signature to be used as they key, (but nothing in cache.c actually
+ * computes or relies on the keys being SHA-1). See mesa-sha1.h and
+ * _mesa_sha1_compute for assistance in computing SHA-1 signatures.
+ */
+
+/* Size of cache keys in bytes. */
+#define CACHE_KEY_SIZE 20
+
+typedef uint8_t cache_key[CACHE_KEY_SIZE];
+
+/**
+ * Create a new cache object.
+ *
+ * This function creates the handle necessary for all subsequent cache_*
+ * functions.
+ */
+struct program_cache *
+cache_create(void);
+
+/**
+ * Store an item in the cache under the name \key.
+ *
+ * The item can be retrieved later with cache_get(), (unless the item has
+ * been evicted).
+ *
+ * Any call to cache_put() may cause an existing, random, item to be evicted
+ * from the cache.
+ */
+void
+cache_put(struct program_cache *cache, cache_key key,
+          const void *data, size_t size);
+
+/**
+ * Mark the cache name \key as used in the cache, (without storing any
+ * associated data).
+ *
+ * A call to cache_mark() is conceptually the same as a call to cache_put()
+ * but without any associated data. Following such a call, cache_get()
+ * cannot be usefully used, (since there is no data to return), but
+ * cache_probe() can be used to check whether <key> has been marked.
+ *
+ * Any call to cache_mark() may cause an existing, random, item to be evicted
+ * from the cache.
+ */
+void
+cache_mark(struct program_cache *cache, cache_key key);
+
+/**
+ * Return an item previously stored in the cache with the name <key>.
+ *
+ * The item must have been previously stored with a call to cache_put().
+ *
+ * If \size is non-NULL, then, on successful return, it will be set to the
+ * size of the object.
+ *
+ * \return A pointer to the stored object, (or NULL if the object is not
+ * found, or if any error occurs such memory allocation failure or a
+ * filesystem error). The returned data is malloc'ed so the caller should call
+ * free() when done with it.
+ */
+uint8_t *
+cache_get(struct program_cache *cache, cache_key key, size_t *size);
+
+/**
+ * A lightweight test whether the given <key> is currently in the cache.
+ *
+ * This test is lightweight in that it makes no syscalls and will not hit the
+ * disk. It is implemented via a small array of \key signatures.
+ *
+ * Return value: True if the item is in the cache (at this instant), false
+ * otherwise.
+ *
+ * Note: After cache_has(), a subsequent call to cache_get()
+ * might fail, (if another user caused the item to be evicted in the
+ * meantime).
+ */
+int
+cache_has(struct program_cache *cache, cache_key key);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CACHE_H */
-- 
2.1.4