The qDecoder Project

qQueue.c File Reference

Circular-Queue Data Structure API. More...


Functions

Q_QUEUEqQueue (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


Copyright (c) 2000-2010 The qDecoder Project