qqueue.c File Reference

Queue implementation. More...

Go to the source code of this file.

Functions
qqueue_t *	qqueue (int options)
	Create new queue container.
size_t	qqueue_setsize (qqueue_t *queue, size_t max)
	qqueue->setsize(): Sets maximum number of elements allowed in this queue.
bool	qqueue_push (qqueue_t *queue, const void *data, size_t size)
	qqueue->push(): Pushes an element onto the top of this queue.
bool	qqueue_pushstr (qqueue_t *queue, const char *str)
	qqueue->pushstr(): Pushes a string onto the top of this queue.
bool	qqueue_pushint (qqueue_t *queue, int64_t num)
	qqueue->pushint(): Pushes an integer onto the top of this queue.
void *	qqueue_pop (qqueue_t *queue, size_t *size)
	qqueue->pop(): Removes an element at the top of this queue and returns that element.
char *	qqueue_popstr (qqueue_t *queue)
	qqueue->popstr(): Removes an element at the top of this queue and returns that element.
int64_t	qqueue_popint (qqueue_t *queue)
	qqueue->popint(): Removes an integer at the top of this queue and returns that element.
void *	qqueue_popat (qqueue_t *queue, int index, size_t *size)
	qqueue->popat(): Returns and removes the element at the specified position in this queue.
void *	qqueue_get (qqueue_t *queue, size_t *size, bool newmem)
	qqueue->get(): Returns an element at the top of this queue without removing it.
char *	qqueue_getstr (qqueue_t *queue)
	qqueue->getstr(): Returns a string at the top of this queue without removing it.
int64_t	qqueue_getint (qqueue_t *queue)
	qqueue->getint(): Returns an integer at the top of this queue without removing it.
void *	qqueue_getat (qqueue_t *queue, int index, size_t *size, bool newmem)
	qqueue->getat(): Returns an element at the specified position in this queue without removing it.
size_t	qqueue_size (qqueue_t *queue)
	qqueue->size(): Returns the number of elements in this queue.
void	qqueue_clear (qqueue_t *queue)
	qqueue->clear(): Removes all of the elements from this queue.
bool	qqueue_debug (qqueue_t *queue, FILE *out)
	qqueue->debug(): Prints stored elements for debugging purposes.
void	qqueue_free (qqueue_t *queue)
	qqueue->free(): Free qqueue_t

Detailed Description

Queue implementation.

qqueue container is a queue implementation. It represents a first-in-first-out(FIFO). It extends qlist container that allow a linked-list to be treated as a queue.

[Conceptional Data Structure Diagram]
 
                    top     bottom
DATA POP    <==    [ A ][ B ][ C ]  <== DATA PUSH
(positive index)     0    1    2
(negative index)    -3   -2   -1

// create queue
qqueue_t *queue = qQueue();
 
// example: integer queue
queue->pushint(queue, 1);
queue->pushint(queue, 2);
queue->pushint(queue, 3);
 
printf("popint(): %d\n", queue->popint(queue));
printf("popint(): %d\n", queue->popint(queue));
printf("popint(): %d\n", queue->popint(queue));
 
// example: string queue
queue->pushstr(queue, "A string");
queue->pushstr(queue, "B string");
queue->pushstr(queue, "C string");
 
char *str = queue->popstr(queue);
printf("popstr(): %s\n", str);
free(str);
str = queue->popstr(queue);
printf("popstr(): %s\n", str);
free(str);
str = queue->popstr(queue);
printf("popstr(): %s\n", str);
free(str);
 
// example: object queue
queue->push(queue, "Object A", sizeof("Object A"));
queue->push(queue, "Object B", sizeof("Object B"));
queue->push(queue, "Object C", sizeof("Object C"));
 
void *obj = queue->pop(queue, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
obj = queue->pop(queue, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
obj = queue->pop(queue, NULL);
printf("pop(): %s\n", (char*)obj);
free(obj);
 
// release
queue->free(queue);
 
[Output]
popint(): 3
popint(): 2
popint(): 1
popstr(): C string
popstr(): B string
popstr(): A string
pop(): Object C
pop(): Object B
pop(): Object A

Definition in file qqueue.c.

Function Documentation

qqueue()

qqueue_t * qqueue

(

int

options

)

Create new queue container.

Parameters

options

combination of initialization options.

Returns

pointer to allocated qqueue container on success, or NULL on failure.

Return values

errno

will be set in error condition. ENOMEM : Memory allocation failure.

qqueue_t *queue = qQueue(QQUEUE_THREADSAFE);

Note

Available options:

• QQUEUE_THREADSAFE - make it thread-safe.

Definition at line 129 of file qqueue.c.

qqueue_setsize()

size_t qqueue_setsize	(	qqueue_t *	queue,
		size_t	max )

qqueue->setsize(): Sets maximum number of elements allowed in this queue.

Parameters

queue	qqueue container pointer.
max	maximum number of elements. 0 means no limit.

Returns

previous maximum number.

Definition at line 177 of file qqueue.c.

qqueue_push()

bool qqueue_push	(	qqueue_t *	queue,
		const void *	data,
		size_t	size )

qqueue->push(): Pushes an element onto the top of this queue.

Parameters

queue	qqueue container pointer.
data	a pointer which points data memory.
size	size of the data.

Returns

true on success, otherwise false.

Return values

errno

will be set in error condition. EINVAL : Invalid argument. ENOBUFS : Queue full. Only happens when this queue has set to have limited number of elements) ENOMEM : Memory allocation failure.

Definition at line 195 of file qqueue.c.

qqueue_pushstr()

bool qqueue_pushstr	(	qqueue_t *	queue,
		const char *	str )

qqueue->pushstr(): Pushes a string onto the top of this queue.

Parameters

queue	qqueue container pointer.
data	a pointer which points data memory.
size	size of the data.

Returns

true on success, otherwise false.

Return values

errno

will be set in error condition. EINVAL : Invalid argument. ENOBUFS : Queue full. Only happens when this queue has set to have limited number of elements. ENOMEM : Memory allocation failure.

Definition at line 213 of file qqueue.c.

qqueue_pushint()

bool qqueue_pushint	(	qqueue_t *	queue,
		int64_t	num )

qqueue->pushint(): Pushes an integer onto the top of this queue.

Parameters

queue	qqueue container pointer.
num	integer data.

Returns

true on success, otherwise false.

Return values

errno

will be set in error condition. ENOBUFS : Queue full. Only happens when this queue has set to have limited number of elements. ENOMEM : Memory allocation failure.

Definition at line 233 of file qqueue.c.

qqueue_pop()

void * qqueue_pop	(	qqueue_t *	queue,
		size_t *	size )

qqueue->pop(): Removes an element at the top of this queue and returns that element.

Parameters

queue	qqueue container pointer.
size	if size is not NULL, element size will be stored.

Returns

pointer to allocated element on success, or NULL on failure.

Return values

errno

will be set in error condition. ENOENT : Queue is empty. ENOMEM : Memory allocation failure.

Definition at line 249 of file qqueue.c.

qqueue_popstr()

char * qqueue_popstr

(

qqueue_t *

queue

)

qqueue->popstr(): Removes an element at the top of this queue and returns that element.

Parameters

queue

qqueue container pointer.

Returns

pointer to allocated string element on success, or NULL on failure.

Return values

errno

will be set in error condition. ENOENT : Queue is empty. ENOMEM : Memory allocation failure.

Note

The string element should be pushed through pushstr().

Definition at line 267 of file qqueue.c.

qqueue_popint()

int64_t qqueue_popint

(

qqueue_t *

queue

)

qqueue->popint(): Removes an integer at the top of this queue and returns that element.

Parameters

queue

qqueue container pointer.

Returns

an integer value, otherwise returns 0.

Return values

errno

will be set in error condition. ENOENT : Queue is empty. ENOMEM : Memory allocation failure.

Note

The integer element should be pushed through pushint().

Definition at line 291 of file qqueue.c.

qqueue_popat()

void * qqueue_popat	(	qqueue_t *	queue,
		int	index,
		size_t *	size )

qqueue->popat(): Returns and removes the element at the specified position in this queue.

Parameters

queue	qqueue container pointer.
index	index of the element to pop
size	if size is not NULL, element size will be stored.

Returns

pointer to allocated element on success, or NULL on failure.

Return values

errno

will be set in error condition. ERANGE : Index out of range. ENOMEM : Memory allocation failure.

Note

Negative index can be used for addressing an element from the bottom in this queue. For example, index -1 will always pop an element which is pushed at very last time.

Definition at line 320 of file qqueue.c.

qqueue_get()

void * qqueue_get	(	qqueue_t *	queue,
		size_t *	size,
		bool	newmem )

qqueue->get(): Returns an element at the top of this queue without removing it.

Parameters

queue	qqueue container pointer.
size	if size is not NULL, element size will be stored.
newmem	whether or not to allocate memory for the element.

Returns

pointer to allocated element on success, or NULL on failure.

Return values

errno

will be set in error condition. ENOENT : Queue is empty. ENOMEM : Memory allocation failure.

Definition at line 337 of file qqueue.c.

qqueue_getstr()

char * qqueue_getstr

(

qqueue_t *

queue

)

qqueue->getstr(): Returns a string at the top of this queue without removing it.

Parameters

queue

qqueue container pointer.

Returns

pointer to allocated string element on success, or NULL on failure.

Return values

errno

will be set in error condition. ENOENT : Queue is empty. ENOMEM : Memory allocation failure.

Note

The string element should be pushed through pushstr().

Definition at line 355 of file qqueue.c.

qqueue_getint()

int64_t qqueue_getint

(

qqueue_t *

queue

)

qqueue->getint(): Returns an integer at the top of this queue without removing it.

Parameters

queue

qqueue container pointer.

Returns

an integer value, otherwise returns 0.

Return values

errno

will be set in error condition. ENOENT : Queue is empty. ENOMEM : Memory allocation failure.

Note

The integer element should be pushed through pushint().

Definition at line 379 of file qqueue.c.

qqueue_getat()

void * qqueue_getat	(	qqueue_t *	queue,
		int	index,
		size_t *	size,
		bool	newmem )

qqueue->getat(): Returns an element at the specified position in this queue without removing it.

Parameters

queue	qqueue container pointer.
index	index at which the specified element is to be inserted
size	if size is not NULL, element size will be stored.
newmem	whether or not to allocate memory for the element.

Returns

pointer to element on success, or NULL on failure.

Return values

errno

will be set in error condition. ERANGE : Index out of range. ENOMEM : Memory allocation failure.

Note

Negative index can be used for addressing an element from the bottom in this queue. For example, index -1 will always get an element which is pushed at very last time.

Definition at line 409 of file qqueue.c.

qqueue_size()

size_t qqueue_size

(

qqueue_t *

queue

)

qqueue->size(): Returns the number of elements in this queue.

Parameters

queue

qqueue container pointer.

Returns

the number of elements in this queue.

Definition at line 420 of file qqueue.c.

qqueue_clear()

void qqueue_clear

(

qqueue_t *

queue

)

qqueue->clear(): Removes all of the elements from this queue.

Parameters

queue

qqueue container pointer.

Definition at line 429 of file qqueue.c.

qqueue_debug()

bool qqueue_debug	(	qqueue_t *	queue,
		FILE *	out )

qqueue->debug(): Prints stored elements for debugging purposes.

Parameters

queue	qqueue container pointer.
out	output stream such as stdout or stderr.

Returns

true on success, otherwise false.

Definition at line 441 of file qqueue.c.

qqueue_free()

void qqueue_free

(

qqueue_t *

queue

)

qqueue->free(): Free qqueue_t

Parameters

queue

qqueue container pointer.

Returns

always returns true.

Definition at line 452 of file qqueue.c.