linked list cleanups

added list methods invoke(), destroy_offset(), destroy_function()
simplified list destruction when destroying its items

1 files changed, 90 insertions, 55 deletions

diff --git a/src/libstrongswan/utils/linked_list.h b/src/libstrongswan/utils/linked_list.h
index 9c824177e..63c7eb6e3 100644
--- a/src/libstrongswan/utils/linked_list.h
+++ b/src/libstrongswan/utils/linked_list.h
@@ -47,21 +47,21 @@ struct linked_list_t {
 	/**
 	 * @brief Gets the count of items in the list.
 	 * 
-	 * @param linked_list 	calling object
-	 * @return 				number of items in list
+	 * @param this 		calling object
+	 * @return 			number of items in list
 	 */
-	int (*get_count) (linked_list_t *linked_list);
+	int (*get_count) (linked_list_t *this);
 	
 	/**
 	 * @brief Creates a iterator for the given list.
 	 * 
 	 * @warning Created iterator_t object has to get destroyed by the caller.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param forward 		iterator direction (TRUE: front to end)
-	 * @return				new iterator_t object
+	 * @param this 		calling object
+	 * @param forward 	iterator direction (TRUE: front to end)
+	 * @return			new iterator_t object
 	 */
-	iterator_t *(*create_iterator) (linked_list_t *linked_list, bool forward);
+	iterator_t *(*create_iterator) (linked_list_t *this, bool forward);
 	
 	/**
 	 * @brief Creates a iterator, locking a mutex.
@@ -69,120 +69,155 @@ struct linked_list_t {
 	 * The supplied mutex is acquired immediately, and released
 	 * when the iterator gets destroyed.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param mutex 		mutex to use for exclusive access
-	 * @return				new iterator_t object
+	 * @param this	 	calling object
+	 * @param mutex 	mutex to use for exclusive access
+	 * @return			new iterator_t object
 	 */
-	iterator_t *(*create_iterator_locked) (linked_list_t *linked_list,
+	iterator_t *(*create_iterator_locked) (linked_list_t *this,
 										   pthread_mutex_t *mutex);
 
 	/**
 	 * @brief Inserts a new item at the beginning of the list.
 	 *
-	 * @param linked_list 	calling object
-	 * @param[in] item		item value to insert in list
+	 * @param this 		calling object
+	 * @param[in] item	item value to insert in list
 	 */
-	void (*insert_first) (linked_list_t *linked_list, void *item);
+	void (*insert_first) (linked_list_t *this, void *item);
 
 	/**
 	 * @brief Removes the first item in the list and returns its value.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param[out] item 	returned value of first item, or NULL
+	 * @param this 		calling object
+	 * @param[out] item returned value of first item, or NULL
 	 * @return
-	 * 						- SUCCESS
-	 * 						- NOT_FOUND, if list is empty
+	 * 					- SUCCESS
+	 * 					- NOT_FOUND, if list is empty
 	 */
-	status_t (*remove_first) (linked_list_t *linked_list, void **item);
+	status_t (*remove_first) (linked_list_t *this, void **item);
 
 	/**
 	 * @brief Returns the value of the first list item without removing it.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param[out] item		item returned value of first item
+	 * @param this	 	calling object
+	 * @param[out] item	returned value of first item
 	 * @return
-	 * 						- SUCCESS
-	 * 						- NOT_FOUND, if list is empty
+	 * 					- SUCCESS
+	 * 					- NOT_FOUND, if list is empty
 	 */
-	status_t (*get_first) (linked_list_t *linked_list, void **item);
+	status_t (*get_first) (linked_list_t *this, void **item);
 
 	/**
 	 * @brief Inserts a new item at the end of the list.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param[in] item 		item value to insert into list
+	 * @param this 		calling object
+	 * @param[in] item 	value to insert into list
 	 */
-	void (*insert_last) (linked_list_t *linked_list, void *item);
+	void (*insert_last) (linked_list_t *this, void *item);
 	
 	/**
 	 * @brief Inserts a new item at a given position in the list.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param position		position starting at 0 to insert new entry
-	 * @param[in] item		item value to insert into list
+	 * @param this		calling object
+	 * @param position	position starting at 0 to insert new entry
+	 * @param[in] item	value to insert into list
 	 * @return
-	 * 						- SUCCESS
-	 * 						- INVALID_ARG if position not existing
+	 * 					- SUCCESS
+	 * 					- INVALID_ARG if position not existing
 	 */
-	status_t (*insert_at_position) (linked_list_t *linked_list,size_t position, void *item);
+	status_t (*insert_at_position) (linked_list_t *this,size_t position, void *item);
 	
 	/**
 	 * @brief Removes an item from a given position in the list.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param position		position starting at 0 to remove entry from
-	 * @param[out] item 	removed item will be stored at this location
+	 * @param this	 	calling object
+	 * @param position	position starting at 0 to remove entry from
+	 * @param[out] item removed item will be stored at this location
 	 * @return
 	 * 						- SUCCESS
 	 * 						- INVALID_ARG if position not existing
 	 */
-	status_t (*remove_at_position) (linked_list_t *linked_list,size_t position, void **item);
+	status_t (*remove_at_position) (linked_list_t *this, size_t position, void **item);
 
 	/**
 	 * @brief Get an item from a given position in the list.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param position		position starting at 0 to get entry from
-	 * @param[out] item		item will be stored at this location
+	 * @param this	 	calling object
+	 * @param position	position starting at 0 to get entry from
+	 * @param[out] item	item will be stored at this location
 	 * @return
 	 * 						- SUCCESS
 	 * 						- INVALID_ARG if position not existing
 	 */
-	status_t (*get_at_position) (linked_list_t *linked_list,size_t position, void **item);
+	status_t (*get_at_position) (linked_list_t *this, size_t position, void **item);
 
 	/**
 	 * @brief Removes the last item in the list and returns its value.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param[out] item		returned value of last item, or NULL
+	 * @param this	 	calling object
+	 * @param[out] item	returned value of last item, or NULL
 	 * @return
 	 * 						- SUCCESS
 	 * 						- NOT_FOUND if list is empty
 	 */
-	status_t (*remove_last) (linked_list_t *linked_list, void **item);
+	status_t (*remove_last) (linked_list_t *this, void **item);
 
 	/**
 	 * @brief Returns the value of the last list item without removing it.
 	 * 
-	 * @param linked_list 	calling object
-	 * @param[out] item		returned value of last item
+	 * @param this 		calling object
+	 * @param[out] item	returned value of last item
 	 * @return
-	 * 						- SUCCESS
-	 * 						- NOT_FOUND if list is empty
+	 * 					- SUCCESS
+	 * 					- NOT_FOUND if list is empty
+	 */
+	status_t (*get_last) (linked_list_t *this, void **item);
+	
+	/**
+	 * @brief Invoke a method on all of the contained objects.
+	 *
+	 * If a linked list contains objects with function pointers,
+	 * invoke() can call a method on each of the objects. The
+	 * method is specified by an offset of the function pointer,
+	 * which can be evalutated at compile time using the offsetof
+	 * macro, e.g.: list->invoke(list, offsetof(object_t, method));
+	 * 
+	 * @param this 		calling object
+	 * @param offset	offset of the method to invoke on objects
 	 */
-	status_t (*get_last) (linked_list_t *linked_list, void **item);
+	void (*invoke) (linked_list_t *this, size_t offset);
 	
 	/**
 	 * @brief Destroys a linked_list object.
 	 * 
-	 * @warning All items are removed before deleting the list. The
-	 *          associated values are NOT destroyed. 
-	 * 			Destroying an list which is not empty may cause
-	 * 			memory leaks!
+	 * @param this		calling object
+	 */
+	void (*destroy) (linked_list_t *this);
+	
+	/**
+	 * @brief Destroys a list and its objects using the destructor.
+	 *
+	 * If a linked list and the contained objects should be destroyed, use
+	 * destroy_offset. The supplied offset specifies the destructor to
+	 * call on each object. The offset may be calculated using the offsetof
+	 * macro, e.g.: list->destroy_offset(list, offsetof(object_t, destroy));
+	 *
+	 * @param this	 	calling object
+	 * @param offset	offset of the objects destructor
+	 */
+	void (*destroy_offset) (linked_list_t *this, size_t offset);
+	
+	/**
+	 * @brief Destroys a list and its contents using a a cleanup function.
 	 * 
-	 * @param linked_list 	calling object
+	 * If a linked list and its contents should get destroyed using a specific
+	 * cleanup function, use destroy_function. This is useful when the
+	 * list contains malloc()-ed blocks which should get freed,
+	 * e.g.: list->destroy_function(list, free);
+	 *
+	 * @param this 		calling object
+	 * @param function	function to call on each object
 	 */
-	void (*destroy) (linked_list_t *linked_list);
+	void (*destroy_function) (linked_list_t *this, void (*)(void*));
 };
 
 /**