#include <stdio.h>
#include <stdlib.h>
#include "pqueue.h"

Functions
PQueue	PQUEUEinit (int(compare)(const void key1, const void key2), void(destroy)(void *data))

void	PQUEUEdestroy (PQueue pq)

int	PQUEUEinsert (PQueue pq, const void *data)

int	PQUEUEextract (PQueue pq, void **data)

const void *	PQUEUEpeek (const PQueue pq)

int	PQUEUEsize (PQueue pq)

void	PQUEUEprint (PQueue pq, void(callback)(const void data))

Function Documentation

void PQUEUEdestroy ( PQueue pq )

Destroy the priority queue

The priority queue is destroyed - that is, all dynamically allocated memory occupied by the elements - will be destroyed. It is the user-defined callback function destroy, given as an argument to PQUEUEinit(), that is responsible for freeing dynamically allocated element data, when this function is called. If, on the other hand, destroy is set to NULL when PQUEUEinit() is called, all element data will be left untouched after the priority queue is dismounted and destroyed. When all elements and data have been deallocated - the rest of the priority queue is freed, too.

Parameters

[in] pq - a reference to current priority queue.

Returns: Nothing.

See Also: PQUEUEinit()

Definition at line 36 of file pqueue.c.

int PQUEUEextract	(	PQueue	pq,
		void **	data
	)

Remove top-priority data from the priority queue

When called, the 2nd parameter of this function, data, should reference an (external, user-defined) pointer. After the call - this referenced, external pointer has been redirected by this function, to point to the data of the removed element - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example.

Parameters

[in]	pq	- reference to current priority queue.
[out]	data	- reference to a pointer. After the call, this referenced pointer has been redirected to point to the data of the removed element - if the call was successful. The caller is responsible for the future of this memory - deallocating it, for example.

Returns: Value 0 – if the call was OK - that is, element removed.
Value -1 – otherwise.

Definition at line 48 of file pqueue.c.

PQueue PQUEUEinit	(	int()(const void key1, const void *key2)	compare,
		void()(void data)	destroy
	)

Initiate the priority queue

Parameters

[in]	compare	- a reference to a user-defined function, used by various priority queue operations to compare elements when operating on the priority queue. This function should return +1 - if key1 > key2 - 0 if the keys are equal - and -1 if key1 < key2. This goes for a top-heavy priority queue. If you want a bottom-heavy priority queue, you should swap the the conditions for returning 1 and -1 instead.
[in]	destroy	- a reference to a user-defined function, reponsible for freeing element data, when the priority queue is destroyed. If destroy is set to NULL - then element data will be left untouched upon priority queue destruction.

Returns: A reference - to a new, empty priority queue - if dynamic memory allocation for the ADT was successful - or NULL otherwise. Take really good care of this return value, since it will be needed as a parameter in subsequent calls - to the majority of other priority queue functions in this function interface - i.e. a sort of "handle" to the priority queue.

Definition at line 30 of file pqueue.c.

int PQUEUEinsert	(	PQueue	pq,
		const void *	data
	)

Insert data into the priority queue

Inserts an element into the current priority queue - referenced by the parameter pq. The data to be inserted, is referenced by parameter data. It is the responsability of the caller to ensure, that this memory is valid as long as it is present in the priority queue.

Parameters

[in]	pq	- a reference to current priority queue.
[in]	data	- a reference to data to be inserted into the priority queue.

Returns: Value 0 - if insertion was succesful
Value -1 - otherwise.

Definition at line 42 of file pqueue.c.

const void* PQUEUEpeek ( const PQueue pq )

Peek at the top-priority element in the queue

Parameters

[in] pq - a reference to the current priority queue.

Returns: A reference to the top-priority element of the current priority queue.

Definition at line 54 of file pqueue.c.

void PQUEUEprint	(	PQueue	pq,
		void()(const void data)	callback
	)

Print data contents of the priority queue on screen

Parameters

[in]	pq	- reference to current priority queue.
[in]	callback	- reference to user-defined callback function, that gets read access to element data via its parameter data - to do whatever is relevant. In this case it is a matter of formatting data for printing on screen. The printed data should be kept to a minimum (the key value, for example) in order not to clutter the screen. This function is primarily for small priority queues - and debugging purposes.

Returns: Nothing.

Definition at line 66 of file pqueue.c.

int PQUEUEsize ( PQueue pq )

Get the number of elements in the priority queue

Parameters

[in] pq - a reference to the current priority queue.

Returns: The size, that is, the number of elements in the priority queue.

Definition at line 60 of file pqueue.c.

Functions

Function Documentation