diff options
Diffstat (limited to 'metis/ccnx/forwarder/metis/content_store/metis_LruList.h')
-rw-r--r-- | metis/ccnx/forwarder/metis/content_store/metis_LruList.h | 180 |
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 |