abawo/pico-sdk
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

No malloc for default alarm pool an pheap docs/cleanup (#143)

Browse Source 
* Statically allocate the default timer pool (to avoid pulling in malloc); doxygen for pheap (and some function name changes)

* fix comments
This commit is contained in:
Graham Sanderson
2021-02-25 08:40:03 -06:00
committed by graham sanderson
parent 0a22f704a6
commit e730e03e7f
3 changed files with 225 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
src/common/pico_util/include/pico/util/pheap.h
View File

@ -29,7 +29,7 @@ extern "C" {
*
* NOTE: this class is not safe for concurrent usage. It should be externally protected. Furthermore
* if used concurrently, the caller needs to protect around their use of the returned id.
* for example, ph_remove_head returns the id of an element that is no longer in the heap.
* for example, ph_remove_and_free_head returns the id of an element that is no longer in the heap.
*
* The user can still use this to look at the data in their companion array, however obviously further operations
* on the heap may cause them to overwrite that data as the id may be reused on subsequent operations
@ -53,7 +53,11 @@ typedef struct pheap_node {
pheap_node_id_t child, sibling, parent;
} pheap_node_t;
// return true if a < b in natural order
/**
* A user comparator function for nodes in a pairing heap.
*
* \return true if a < b in natural order. Note this relative ordering must be stable from call to call.
*/
typedef bool (*pheap_comparator)(void *user_data, pheap_node_id_t a, pheap_node_id_t b);
typedef struct pheap {
@ -67,17 +71,42 @@ typedef struct pheap {
pheap_node_id_t free_tail_id;
} pheap_t;
/**
* Create a pairing heap, which effectively maintains an efficient sorted ordering
* of nodes. The heap itself stores no user per-node state, it is expected
* that the user maintains a companion array. A comparator function must
* be provided so that the heap implementation can determine the relative ordering of nodes
*
* \param max_nodes the maximum number of nodes that may be in the heap (this is bounded by
* PICO_PHEAP_MAX_ENTRIES which defaults to 255 to be able to store indexes
* in a single byte).
* \param comparator the node comparison function
* \param user_data a user data pointer associated with the heap that is provided in callbacks
* \return a newly allocated and initialized heap
*/
pheap_t *ph_create(uint max_nodes, pheap_comparator comparator, void *user_data);
/**
* Removes all nodes from the pairing heap
* \param heap the heap
*/
void ph_clear(pheap_t *heap);
/**
* De-allocates a pairing heap
*
* Note this method must *ONLY* be called on heaps created by ph_create()
* \param heap the heap
*/
void ph_destroy(pheap_t *heap);
// internal method
static inline pheap_node_t *ph_get_node(pheap_t *heap, pheap_node_id_t id) {
assert(id && id <= heap->max_nodes);
return heap->nodes + id - 1;
}
// internal method
static void ph_add_child_node(pheap_t *heap, pheap_node_id_t parent_id, pheap_node_id_t child_id) {
pheap_node_t *n = ph_get_node(heap, parent_id);
assert(parent_id);
@ -93,6 +122,7 @@ static void ph_add_child_node(pheap_t *heap, pheap_node_id_t parent_id, pheap_no
}
}
// internal method
static pheap_node_id_t ph_merge_nodes(pheap_t *heap, pheap_node_id_t a, pheap_node_id_t b) {
if (!a) return b;
if (!b) return a;
@ -105,17 +135,34 @@ static pheap_node_id_t ph_merge_nodes(pheap_t *heap, pheap_node_id_t a, pheap_no
}
}
/**
* Allocate a new node from the unused space in the heap
*
* \param heap the heap
* \return an identifier for the node, or 0 if the heap is full
*/
static inline pheap_node_id_t ph_new_node(pheap_t *heap) {
if (!heap->free_head_id) return 0;
pheap_node_id_t id = heap->free_head_id;
heap->free_head_id = ph_get_node(heap, id)->sibling;
pheap_node_t *hn = ph_get_node(heap, id);
heap->free_head_id = hn->sibling;
if (!heap->free_head_id) heap->free_tail_id = 0;
hn->child = hn->sibling = hn->parent = 0;
return id;
}
// note this will callback the comparator for the node
// returns the (new) root of the heap
static inline pheap_node_id_t ph_insert(pheap_t *heap, pheap_node_id_t id) {
/**
* Inserts a node into the heap.
*
* This method inserts a node (previously allocated by ph_new_node())
* into the heap, determining the correct order by calling
* the heap's comparator
*
* \param heap the heap
* \param id the id of the node to insert
* \return the id of the new head of the pairing heap (i.e. node that compares first)
*/
static inline pheap_node_id_t ph_insert_node(pheap_t *heap, pheap_node_id_t id) {
assert(id);
pheap_node_t *hn = ph_get_node(heap, id);
hn->child = hn->sibling = hn->parent = 0;
@ -123,31 +170,120 @@ static inline pheap_node_id_t ph_insert(pheap_t *heap, pheap_node_id_t id) {
return heap->root_id;
}
/**
* Returns the head node in the heap, i.e. the node
* which compares first, but without removing it from the heap.
*
* \param heap the heap
* \return the current head node id
*/
static inline pheap_node_id_t ph_peek_head(pheap_t *heap) {
return heap->root_id;
}
pheap_node_id_t ph_remove_head_reserve(pheap_t *heap, bool reserve);
/**
* Remove the head node from the pairing heap. This head node is
* the node which compares first in the logical ordering provided
* by the comparator.
*
* Note that in the case of free == true, the returned id is no longer
* allocated and may be re-used by future node allocations, so the caller
* should retrieve any per node state from the companion array before modifying
* the heap further.
*
* @param heap the heap
* @param free true if the id is also to be freed; false if not - useful if the caller
* may wish to re-insert an item with the same id)
* @return the old head node id.
*/
pheap_node_id_t ph_remove_head(pheap_t *heap, bool free);
static inline pheap_node_id_t ph_remove_head(pheap_t *heap) {
return ph_remove_head_reserve(heap, false);
/**
* Remove the head node from the pairing heap. This head node is
* the node which compares first in the logical ordering provided
* by the comparator.
*
* Note that the returned id will be freed, and thus may be re-used by future node allocations,
* so the caller should retrieve any per node state from the companion array before modifying
* the heap further.
*
* @param heap the heap
* @return the old head node id.
*/
static inline pheap_node_id_t ph_remove_and_free_head(pheap_t *heap) {
return ph_remove_head(heap, true);
}
static inline bool ph_contains(pheap_t *heap, pheap_node_id_t id) {
/**
* Remove and free an arbitrary node from the pairing heap. This is a more
* costly operation than removing the head via ph_remove_and_free_head()
*
* @param heap the heap
* @param id the id of the node to free
* @return true if the the node was in the heap, false otherwise
*/
bool ph_remove_and_free_node(pheap_t *heap, pheap_node_id_t id);
/**
* Determine if the heap contains a given node. Note containment refers
* to whether the node is inserted (ph_insert_node()) vs allocated (ph_new_node())
*
* @param heap the heap
* @param id the id of the node
* @return true if the heap contains a node with the given id, false otherwise.
*/
static inline bool ph_contains_node(pheap_t *heap, pheap_node_id_t id) {
return id == heap->root_id || ph_get_node(heap, id)->parent;
}
bool ph_delete(pheap_t *heap, pheap_node_id_t id);
static inline void ph_add_to_free_list(pheap_t *heap, pheap_node_id_t id) {
assert(id && !ph_contains(heap, id));
/**
* Free a node that is not currently in the heap, but has been allocated
*
* @param heap the heap
* @param id the id of the node
*/
static inline void ph_free_node(pheap_t *heap, pheap_node_id_t id) {
assert(id && !ph_contains_node(heap, id));
if (heap->free_tail_id) {
ph_get_node(heap, heap->free_tail_id)->sibling = id;
}
heap->free_tail_id = id;
}
void ph_dump(pheap_t *heap, void (*dump_key)(pheap_node_id_t, void *), void *user_data);
/**
* Print a representation of the heap for debugging
*
* @param heap the heap
* @param dump_key a method to print a node value
* @param user_data the user data to pass to the dump_key method
*/
void ph_dump(pheap_t *heap, void (*dump_key)(pheap_node_id_t id, void *user_data), void *user_data);
/**
* Initialize a statically allocated heap (ph_create() using the C heap).
* The heap member `nodes` must be allocated of size max_nodes.
*
* @param heap the heap
* @param max_nodes the max number of nodes in the heap (matching the size of the heap's nodes array)
* @param comparator the comparator for the heap
* @param user_data the user data for the heap.
*/
void ph_post_alloc_init(pheap_t *heap, uint max_nodes, pheap_comparator comparator, void *user_data);
/**
* Define a statically allocated pairing heap. This must be initialized
* by ph_post_alloc_init
*/
#define PHEAP_DEFINE_STATIC(name, _max_nodes) \
static_assert(_max_nodes && _max_nodes < (1u << (8 * sizeof(pheap_node_id_t))), ""); \
static pheap_node_t name ## _nodes[_max_nodes]; \
static pheap_t name = { \
.nodes = name ## _nodes, \
.max_nodes = _max_nodes \
};
#ifdef __cplusplus
}
#endif

26
src/common/pico_util/pheap.c
View File

@ -9,14 +9,19 @@
#include "pico/util/pheap.h"
pheap_t *ph_create(uint max_nodes, pheap_comparator comparator, void *user_data) {
invalid_params_if(PHEAP, !max_nodes || max_nodes >= (1u << sizeof(pheap_node_id_t)));
invalid_params_if(PHEAP, !max_nodes || max_nodes >= (1u << (8 * sizeof(pheap_node_id_t))));
pheap_t *heap = calloc(1, sizeof(pheap_t));
heap->nodes = calloc(max_nodes, sizeof(pheap_node_t));
ph_post_alloc_init(heap, max_nodes, comparator, user_data);
return heap;
}
void ph_post_alloc_init(pheap_t *heap, uint max_nodes, pheap_comparator comparator, void *user_data) {
invalid_params_if(PHEAP, !max_nodes || max_nodes >= (1u << (8 * sizeof(pheap_node_id_t))));
heap->max_nodes = (pheap_node_id_t) max_nodes;
heap->comparator = comparator;
heap->nodes = calloc(max_nodes, sizeof(pheap_node_t));
heap->user_data = user_data;
ph_clear(heap);
return heap;
}
void ph_clear(pheap_t *heap) {
@ -47,13 +52,13 @@ pheap_node_id_t ph_merge_two_pass(pheap_t *heap, pheap_node_id_t id) {
}
}
static pheap_node_id_t ph_remove_any_head(pheap_t *heap, pheap_node_id_t root_id, bool reserve) {
static pheap_node_id_t ph_remove_any_head(pheap_t *heap, pheap_node_id_t root_id, bool free) {
assert(root_id);
// printf("Removing head %d (parent %d sibling %d)\n", root_id, ph_get_node(heap, root_id)->parent, ph_get_node(heap, root_id)->sibling);
assert(!ph_get_node(heap, root_id)->sibling);
assert(!ph_get_node(heap, root_id)->parent);
pheap_node_id_t new_root_id = ph_merge_two_pass(heap, ph_get_node(heap, root_id)->child);
if (!reserve) {
if (free) {
if (heap->free_tail_id) {
ph_get_node(heap, heap->free_tail_id)->sibling = root_id;
}
@ -64,18 +69,17 @@ static pheap_node_id_t ph_remove_any_head(pheap_t *heap, pheap_node_id_t root_id
return new_root_id;
}
pheap_node_id_t ph_remove_head_reserve(pheap_t *heap, bool reserve) {
pheap_node_id_t ph_remove_head(pheap_t *heap, bool free) {
pheap_node_id_t old_root_id = ph_peek_head(heap);
heap->root_id = ph_remove_any_head(heap, old_root_id, reserve);
heap->root_id = ph_remove_any_head(heap, old_root_id, free);
return old_root_id;
}
#include <stdio.h>
bool ph_delete(pheap_t *heap, pheap_node_id_t id) {
bool ph_remove_and_free_node(pheap_t *heap, pheap_node_id_t id) {
// 1) trivial cases
if (!id) return false;
if (id == heap->root_id) {
ph_remove_head(heap);
ph_remove_and_free_head(heap);
return true;
}
// 2) unlink the node from the tree
@ -101,7 +105,7 @@ bool ph_delete(pheap_t *heap, pheap_node_id_t id) {
node->sibling = node->parent = 0;
// ph_dump(heap, NULL, NULL);
// 3) remove it from the head of its own subtree
pheap_node_id_t new_sub_tree = ph_remove_any_head(heap, id, false);
pheap_node_id_t new_sub_tree = ph_remove_any_head(heap, id, true);
assert(new_sub_tree != heap->root_id);
heap->root_id = ph_merge_nodes(heap, heap->root_id, new_sub_tree);
return true;