update entry points to backing store ready for allowing differing object lifetimes

3 files changed, 89 insertions, 15 deletions

diff --git a/content/backing_store.h b/content/backing_store.h
index 849e11aeb..2b986cf52 100644
--- a/content/backing_store.h
+++ b/content/backing_store.h
@@ -27,13 +27,12 @@
 
 /** storage control flags */
 enum backing_store_flags {
-	BACKING_STORE_NONE = 0, /**< no special processing */
-	BACKING_STORE_META = 1, /**< data is metadata */
-	BACKING_STORE_MMAP = 2, /**< when data is retrived this indicates the
-				 * returned buffer may be memory mapped,
-				 * flag must be cleared if the storage is
-				 * allocated and is not memory mapped.
-				 */
+	/** no special processing */
+	BACKING_STORE_NONE = 0,
+	/** data is metadata */
+	BACKING_STORE_META = 1,
+	/** backing store will handle allocation. */
+	BACKING_STORE_ALLOC = 2
 };
 
 /** low level cache backing store operation table
@@ -61,10 +60,18 @@ struct gui_llcache_table {
 	/**
 	 * Place an object in the backing store.
 	 *
-	 * @param url The url is used as the unique primary key for the data.
-	 * @param flags The flags to control how the obejct is stored.
-	 * @param data The objects data.
-	 * @param datalen The length of the \a data.
+	 * The object is placed in the persistent store and may be
+	 * retrieved. If the BACKING_STORE_ALLOC flag is used the
+	 * backing store will take a reference to the passed data,
+	 * subsequently the caller should explicitly release the
+	 * allocation using the release method and not free the data
+	 * itself. An additional effect of this is that the persistent
+	 * storage may not have been completely written on return.
+	 *
+	 * @param[in] url The url is used as the unique primary key for the data.
+	 * @param[in] flags The flags to control how the obejct is stored.
+	 * @param[in] data The objects data.
+	 * @param[in] datalen The length of the \a data.
 	 * @return NSERROR_OK on success or error code on faliure.
 	 */
 	nserror (*store)(struct nsurl *url, enum backing_store_flags flags,
@@ -73,10 +80,14 @@ struct gui_llcache_table {
 	/**
 	 * Retrive an object from the backing store.
 	 *
-	 * @param url The url is used as the unique primary key for the data.
-	 * @param flags The flags to control how the object is retrived.
-	 * @param data The objects data.
-	 * @param datalen The length of the \a data retrieved.
+	 * If the BACKING_STORE_ALLOC flag is set the returned memory
+	 * is managed by the backing store and should be freed by
+	 * calling the release method.
+	 *
+	 * @param[in] url The url is used as the unique primary key for the data.
+	 * @param[in] flags The flags to control how the object is retrived.
+	 * @param[in,out] data The retrived objects data.
+	 * @param[in,out] datalen The length of the \a data retrieved.
 	 * @return NSERROR_OK on success or error code on faliure.
 	 */
 	nserror (*fetch)(struct nsurl *url, enum backing_store_flags *flags,
@@ -88,10 +99,26 @@ struct gui_llcache_table {
 	 * The entry (if present in the backing store) must no longer
 	 * be returned as a result to the fetch or meta operations.
 	 *
+	 * If the entry had data allocated it will be released.
+	 *
 	 * @param url The url is used as the unique primary key to invalidate.
 	 * @return NSERROR_OK on success or error code on faliure.
 	 */
 	nserror (*invalidate)(struct nsurl *url);
+
+	/**
+	 * release a previously fetched or stored memory object.
+	 *
+	 * if the BACKING_STORE_ALLOC flag was used with the fetch or
+	 * store operation for this url the returned storage is
+	 * unreferenced. When the reference count drops to zero the
+	 * storage is released.
+	 *
+	 * @param url The url is used as the unique primary key to invalidate.
+	 * @param[in] flags The flags to control how the object data is released.
+	 * @return NSERROR_OK on success or error code on faliure.
+	 */
+	nserror (*release)(struct nsurl *url, enum backing_store_flags flags);
 };
 
 extern struct gui_llcache_table* null_llcache_table;
diff --git a/content/fs_backing_store.c b/content/fs_backing_store.c
index ba365a222..fdac343ff 100644
--- a/content/fs_backing_store.c
+++ b/content/fs_backing_store.c
@@ -73,8 +73,19 @@
 /** Filename of serialised entries */
 #define ENTRIES_FNAME "entries"
 
+/**
+ * flags that indicate what additional information is contained within
+ * an entry.
+ */
 enum store_entry_flags {
+	/** entry is not managing the allocation */
 	STORE_ENTRY_FLAG_NONE = 0,
+        /** entry allocation is on heap */
+	STORE_ENTRY_FLAG_HEAP = 1,
+        /** entry allocation is mmaped */
+	STORE_ENTRY_FLAG_MMAP = 2,
+        /** entry allocation is in small object pool */
+	STORE_ENTRY_FLAG_SMALL = 4,
 };
 
 /**
@@ -1303,12 +1314,30 @@ invalidate(nsurl *url)
 }
 
 
+/**
+ * release a previously fetched or stored memory object.
+ *
+ * if the BACKING_STORE_ALLOC flag was used with the fetch or
+ * store operation for this url the returned storage is
+ * unreferenced. When the reference count drops to zero the
+ * storage is released.
+ *
+ * @param url The url is used as the unique primary key to invalidate.
+ * @param[in] flags The flags to control how the object data is released.
+ * @return NSERROR_OK on success or error code on faliure.
+ */
+static nserror release(nsurl *url, enum backing_store_flags flags)
+{
+	return NSERROR_NOT_FOUND;
+}
+
 static struct gui_llcache_table llcache_table = {
 	.initialise = initialise,
 	.finalise = finalise,
 	.store = store,
 	.fetch = fetch,
 	.invalidate = invalidate,
+	.release = release,
 };
 
 struct gui_llcache_table *filesystem_llcache_table = &llcache_table;
diff --git a/content/no_backing_store.c b/content/no_backing_store.c
index 192101522..917d68a11 100644
--- a/content/no_backing_store.c
+++ b/content/no_backing_store.c
@@ -57,12 +57,30 @@ static nserror invalidate(nsurl *url)
 	return NSERROR_NOT_FOUND;
 }
 
+/**
+ * release a previously fetched or stored memory object.
+ *
+ * if the BACKING_STORE_ALLOC flag was used with the fetch or
+ * store operation for this url the returned storage is
+ * unreferenced. When the reference count drops to zero the
+ * storage is released.
+ *
+ * @param url The url is used as the unique primary key to invalidate.
+ * @param[in] flags The flags to control how the object data is released.
+ * @return NSERROR_OK on success or error code on faliure.
+ */
+static nserror release(nsurl *url, enum backing_store_flags flags)
+{
+	return NSERROR_NOT_FOUND;
+}
+
 static struct gui_llcache_table llcache_table = {
 	.initialise = initialise,
 	.finalise = finalise,
 	.store = store,
 	.fetch = fetch,
 	.invalidate = invalidate,
+	.release = release,
 };
 
 struct gui_llcache_table *null_llcache_table = &llcache_table;