pqueue.h File Reference

Priority Queue function declarations. More...

#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	pqueue_t
	the priority queue handle More...
typedef unsigned long long	pqueue_pri_t
	priority data type (used to be double, but ull is 107 times faster)
typedef pqueue_pri_t(*	pqueue_get_pri_f )(void *a)
	callback functions to get/set/compare the priority of an element
typedef void(*	pqueue_set_pri_f )(void *a, pqueue_pri_t pri)
typedef int(*	pqueue_cmp_pri_f )(pqueue_pri_t next, pqueue_pri_t curr)
typedef unsigned int(*	pqueue_get_pos_f )(void *a)
	callback functions to get/set the position of an element
typedef void(*	pqueue_set_pos_f )(void *a, unsigned int pos)
typedef void(*	pqueue_print_entry_f )(FILE *out, void *a)
	debug callback function to print a entry
pqueue_t *	pqueue_init (unsigned int n, pqueue_cmp_pri_f cmppri, pqueue_get_pri_f getpri, pqueue_set_pri_f setpri, pqueue_get_pos_f getpos, pqueue_set_pos_f setpos)
	initialize the queue
void	pqueue_free (pqueue_t *q)
	free all memory used by the queue
unsigned int	pqueue_size (pqueue_t *q)
	return the size of the queue.
int	pqueue_insert (pqueue_t *q, void *d)
	insert an item into the queue.
void	pqueue_change_priority (pqueue_t *q, pqueue_pri_t new_pri, void *d)
	move an existing entry to a different priority
void *	pqueue_pop (pqueue_t *q)
	pop the highest-ranking item from the queue.
int	pqueue_remove (pqueue_t *q, void *d)
	remove an item from the queue.
void *	pqueue_peek (pqueue_t *q)
	access highest-ranking item without removing it.
void	pqueue_print (pqueue_t *q, FILE *out, pqueue_print_entry_f print)
	print the queue
void	pqueue_dump (pqueue_t *q, FILE *out, pqueue_print_entry_f print)
	dump the queue and it's internal structure
int	pqueue_is_valid (pqueue_t *q)
	checks that the pq is in the right order, etc

---

Detailed Description

Priority Queue function declarations.

This priority queue library was originally written by Volkan Yazici <volkan.yazici@gmail.com>. It was lated adapted for Nagios by Andreas Ericsson <ae@op5.se>. Changes compared to the original version are pretty much limited to changing pqueue_pri_t to be an unsigned long long instead of a double, since ULL comparisons are 107 times faster on my 64-bit laptop.

---

Function Documentation

void pqueue_change_priority	(	pqueue_t *	q,
		pqueue_pri_t	new_pri,
		void *	d
	)

move an existing entry to a different priority

Parameters:

	q	the queue
	new_pri	the new priority
	d	the entry

void pqueue_free

(

pqueue_t *

q

)

free all memory used by the queue

Parameters:

q

the queue

pqueue_t* pqueue_init	(	unsigned int	n,
		pqueue_cmp_pri_f	cmppri,
		pqueue_get_pri_f	getpri,
		pqueue_set_pri_f	setpri,
		pqueue_get_pos_f	getpos,
		pqueue_set_pos_f	setpos
	)

initialize the queue

Parameters:

	n	the initial estimate of the number of queue items for which memory should be preallocated
	cmppri	The callback function to run to compare two elements This callback should return 0 for 'lower' and non-zero for 'higher', or vice versa if reverse priority is desired
	setpri	the callback function to run to assign a score to an element
	getpri	the callback function to run to set a score to an element
	getpos	the callback function to get the current element's position
	setpos	the callback function to set the current element's position

Returns:

the handle or NULL for insufficent memory

int pqueue_insert	(	pqueue_t *	q,
		void *	d
	)

insert an item into the queue.

Parameters:

	q	the queue
	d	the item

Returns:

0 on success

void* pqueue_peek

(

pqueue_t *

q

)

access highest-ranking item without removing it.

Parameters:

q

the queue

Returns:

NULL on error, otherwise the entry

void* pqueue_pop

(

pqueue_t *

q

)

pop the highest-ranking item from the queue.

Parameters:

q

the queue

Returns:

NULL on error, otherwise the entry

int pqueue_remove	(	pqueue_t *	q,
		void *	d
	)

remove an item from the queue.

Parameters:

	q	the queue
	d	the entry

Returns:

0 on success

unsigned int pqueue_size

(

pqueue_t *

q

)

return the size of the queue.

Parameters:

q

the queue