---

qQueue.c File Reference

Circular-Queue Data Structure API. More...

Functions
Q_QUEUE *	qQueue (int max, size_t objsize)
	Initialize queue.
int	qQueueUsrmem (Q_QUEUE *queue, void *datamem, size_t memsize, size_t objsize)
	Initialize queue which uses user's memory.
static bool	_push (Q_QUEUE *queue, const void *object)
	Q_QUEUE->push(): Push object into queue.
static void *	_popFirst (Q_QUEUE *queue, bool remove)
	Q_QUEUE->popFirst(): Pop first pushed object from queue.
static void *	_popLast (Q_QUEUE *queue, bool remove)
	Q_QUEUE->popLast(): Pop last pushed object from queue.
static int	_getNum (Q_QUEUE *queue)
	Q_QUEUE->getNum(): Get number of objects queued.
static int	_getAvail (Q_QUEUE *queue)
	Q_QUEUE->getAvail(): Get number of objects can be queued.
static void	_truncate (Q_QUEUE *queue)
	Q_QUEUE->truncate(): Truncate queue.
static void	_free (Q_QUEUE *queue)
	Q_QUEUE->free(): De-allocate queue.
static void	_freeUsrmem (Q_QUEUE *queue)

---

Detailed Description

Circular-Queue Data Structure API.

   ----[Sample codes]----
   struct myobj {
     int integer;
     char string[255+1];
   };

   int main(void) {
     Q_QUEUE *queue = qQueue(100, sizeof(struct myobj));

     // push object
     int i;
     for(i = 1; ; i++) {
       // set sample object
       struct myobj obj;
       obj.integer = i;
       sprintf(obj.string, "hello world %d", i);

       // push object
       if(queue->push(queue, &obj) == false) break;

       // print debug info
       printf("Push     : %d, %s\n", obj.integer, obj.string);
     }

     // pop object from head & tail
     while(true) {
       struct myobj pop;
       if(queue->popFirst(queue, &pop) == false) break;
       printf("PopFirst : %d, %s\n", pop.integer, pop.string);

       if(queue->popLast(queue, &pop) == false) break;
       printf("PopLast  : %d, %s\n", pop.integer, pop.string);
     }
     return 0;
   }

   ----[Results]----
   Push     : 1, hello world 1
   Push     : 2, hello world 2
   Push     : 3, hello world 3
   Push     : 4, hello world 4
   Push     : 5, hello world 5
   Push     : 6, hello world 6
   Push     : 7, hello world 7
   Push     : 8, hello world 8
   Push     : 9, hello world 9
   Push     : 10, hello world 10
   PopFirst : 1, hello world 1
   PopLast  : 10, hello world 10
   PopFirst : 2, hello world 2
   PopLast  : 9, hello world 9
   PopFirst : 3, hello world 3
   PopLast  : 8, hello world 8
   PopFirst : 4, hello world 4
   PopLast  : 7, hello world 7
   PopFirst : 5, hello world 5
   PopLast  : 6, hello world 6

Note:

Use "--enable-threadsafe" configure script option to use under multi-threaded environments.

---

Function Documentation

Q_QUEUE* qQueue	(	int	max,
		size_t	objsize
	)

Initialize queue.

Parameters:

	max	a number of maximum internal slots
	objsize	size of queuing object

Returns:

maximum number of queuing objects

   Q_QUEUE *queue = qQueue(100, sizeof(struct myobj));
   if(queue == NULL) {
     printf("Can't initialize queue.\n");
     return -1;
   }

   // free
   queue.free(); // this will de-allocate every thing

int qQueueUsrmem	(	Q_QUEUE *	queue,
		void *	datamem,
		size_t	memsize,
		size_t	objsize
	)

Initialize queue which uses user's memory.

Parameters:

	queue	a pointer of Q_QUEUE
	datamem	a pointer of data memory
	memsize	size of datamem
	objsize	size of queuing object

Returns:

maximum number of queuable objects

   size_t memsize = sizeof(obj) * 100;
   void *datamem = malloc(memsize);
   Q_QUEUE queue;
   if(qQueueUsrmem(&queue, datamem, memsize, sizeof(obj)) == 0) {
     printf("Can't initialize queue.\n");
     return -1;
   }

   // free
   queue.free(); // this will not de-allocate structure but de-allocate internal MUTEX if it's compiled with thread-safe feature

Note:

This implementation is designed to use statically allocated(fixed-size) memory for flexibilities. So you can use this queue with in shared-memory architecture to communicate with other processors. The size of datamem can be calculated with (expected_max_data_in_queue * object_size).

static bool _push	(	Q_QUEUE *	queue,
		const void *	object
	)			[static]

Q_QUEUE->push(): Push object into queue.

Parameters:

	queue	a pointer of Q_QUEUE
	object	object pointer which points object data to push

Returns:

true if successful, otherwise(queue full or not initialized) returns false

static void* _popFirst	(	Q_QUEUE *	queue,
		bool	remove
	)			[static]

Q_QUEUE->popFirst(): Pop first pushed object from queue.

Parameters:

	queue	a pointer of Q_QUEUE
	remove	set true for pop & remove otherwise data will not be removed.

Returns:

object pointer which malloced if successful, otherwise returns NULL

Note:

Can be used for FIFO implementation

static void* _popLast	(	Q_QUEUE *	queue,
		bool	remove
	)			[static]

Q_QUEUE->popLast(): Pop last pushed object from queue.

Parameters:

	queue	a pointer of Q_QUEUE
	remove	set true for pop & remove otherwise data will not be removed.

Returns:

object pointer which is malloced if successful, otherwise return NULL

Note:

Can be used for STACK implementation

static int _getNum

(

Q_QUEUE *

queue

)

[static]

Q_QUEUE->getNum(): Get number of objects queued.

Parameters:

queue

a pointer of Q_QUEUE

Returns:

number of objects queued

static int _getAvail

(

Q_QUEUE *

queue

)

[static]

Q_QUEUE->getAvail(): Get number of objects can be queued.

Parameters:

queue

a pointer of Q_QUEUE

Returns:

number of objects queued

static void _truncate

(

Q_QUEUE *

queue

)

[static]

Q_QUEUE->truncate(): Truncate queue.

Parameters:

queue

a pointer of Q_QUEUE

Returns:

true if successful, otherwise returns false

Note:

You do not need to call this, after qQueueInit(). This is useful when you reset all of data in the queue.

static void _free

(

Q_QUEUE *

queue

)

[static]

Q_QUEUE->free(): De-allocate queue.

Parameters:

queue

a pointer of Q_QUEUE

Returns:

true if successful, otherwise returns false

---

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]