1 files changed, 180 insertions, 0 deletions
diff --git a/metis/ccnx/forwarder/metis/content_store/metis_LruList.h b/metis/ccnx/forwarder/metis/content_store/metis_LruList.h
new file mode 100644
index 00000000..906f8c50
--- /dev/null
+++ b/metis/ccnx/forwarder/metis/content_store/metis_LruList.h
@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file metis_LruList.h
+ * @brief Maintains an LRU for the content store
+ *
+ * An LRU list is make up of LRU entries.  The entries are bound to the list.
+ * The user of the list is reponsible for knowing when there's too many things and
+ * wants to remove one.  The LRU list will grow without bound otherwise.
+ *
+ * The LRU list is meant to be used as an auxiliary data structure, not the primary
+ * storage of data elements.
+ *
+ * Example Usage:
+ *
+ * <code>
+ *  myClass_Create() {
+ *      ...
+ *      me->lru = metisLruList_Create();
+ *      ...
+ *  }
+ *
+ *  myClass_AddAnItem(MyClass *me, ...) {
+ *     size_t length = metisLruList_Length(me->lru);
+ *     if( lenth == me->limit )
+ *        myClass_Overflow(me);
+ *
+ *     item_Create(me, ...);
+ *  }
+ *
+ *  myClass_Overflow(MyClass *me) {
+ *     MetisLruEntry *entry = metisLruList_PopTail(me->lru);
+ *
+ *     // entry could be NULL, if the list is empty, but you probalby wouldnt have overflow then...
+ *     Item *item = (Item *) metisLruEntry_GetData(entry);
+ *     item_Destroy(&item);
+ *  }
+ *
+ *  myClass_Destroy(MyClass *me) {
+ *     // this does not destroy the void * data in the entries, just the entries.
+ *     metisLruList_Destroy(&me->lru);
+ *     // destroy all the items from some other knowledge
+ *  }
+ *
+ *  item_Create(MyClass *me, ...) {
+ *     item = malloc(sizeof(Item));
+ *     MetisLruEntry *entry = metisLruList_NewHeadEntry(me->lru, item);
+ *     item->lruEntry = entry;
+ *     ...
+ *  }
+ *
+ *  item_Use(Item *item) {
+ *     metisLruEntry_MoveToHead(item->lruEntry);
+ *     ...
+ *  }
+ *
+ *  item_Destroy(Item *item) {
+ *     // removes the entry from the list, if its in a list
+ *     metisLruEntry_Destroy(&item->lruEntry);
+ *     free(item);
+ *  }
+ *
+ */
+
+#ifndef Metis_metis_LruList_h
+#define Metis_metis_LruList_h
+
+struct metis_lru_list_entry;
+typedef struct metis_lru_list_entry MetisLruListEntry;
+
+struct metis_lru_list;
+typedef struct metis_lru_list MetisLruList;
+
+/**
+ * @function metisLruEntry_Destroy
+ * @abstract Destroys and element.  This will also remove it from the list.
+ * @discussion
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ */
+void metisLruList_EntryDestroy(MetisLruListEntry **entryPtr);
+
+/**
+ * @function <#FunctionName#>
+ * @abstract <#OneLineDescription#>
+ * @discussion
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ */
+void metisLruList_EntryMoveToHead(MetisLruListEntry *entry);
+
+/**
+ * @function metisLruEntry_GetData
+ * @abstract Returns the user-supplied opaque data when the entry was created
+ * @discussion
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ */
+void *metisLruList_EntryGetData(MetisLruListEntry *entry);
+
+/**
+ * @function metisLruList_Create
+ * @abstract Creates a new Least-Recently-Used list
+ * @discussion
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ */
+MetisLruList *metisLruList_Create();
+
+/**
+ * @function metisLruList_Destroy
+ * @abstract Destroys a list and frees all the elements in it
+ * @discussion
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ */
+void metisLruList_Destroy(MetisLruList **listPtr);
+
+/**
+ * Returns the number of items in the list
+ *
+ * <#Paragraphs Of Explanation#>
+ *
+ * @param [in] lru An allocated MetisLruList
+ *
+ * @retval number The number of items in the LRU list
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+size_t metisLruList_Length(const MetisLruList *lru);
+
+/**
+ * @function metisLruList_NewHeadEntry
+ * @abstract Creates a new entry for the list.  It is inserted at the head of the list.
+ * @discussion
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ */
+MetisLruListEntry *metisLruList_NewHeadEntry(MetisLruList *lru, void *data);
+
+/**
+ * @function metisLruList_PopTail
+ * @abstract Removes the tail element from the list and returns it to the user
+ * @discussion
+ *   Pops the tail element.  The user should examine its data to destroy their
+ *   tail object, then call <code>MetisLruEntry_Destroy()</code> to free the
+ *   LRU entry.
+ *
+ * @param <#param1#>
+ * @return The tail element, or NULL for an empty list
+ */
+MetisLruListEntry *metisLruList_PopTail(MetisLruList *list);
+#endif // Metis_metis_LruList_h