The qDecoder Project

qQueue.c File Reference

Circular-Queue Data Structure API. More...


Functions

size_t qQueueSize (int max, size_t objsize)
 Get how much memory is needed for N objects.
int qQueueInit (Q_QUEUE *queue, void *datamem, size_t datamemsize, size_t objsize)
 Initialize queue.
bool qQueueClear (Q_QUEUE *queue)
 Reset queue.
bool qQueuePush (Q_QUEUE *queue, const void *object)
 Push object into queue.
bool qQueuePopFirst (Q_QUEUE *queue, void *object)
 Pop first pushed object from queue.
bool qQueuePopLast (Q_QUEUE *queue, void *object)
 Pop last pushed object from queue.
bool qQueueStatus (Q_QUEUE *queue, int *used, int *max)
 Get queue internal status.


Detailed Description

Circular-Queue Data Structure API.

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.

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

   int main(void) {
     // allocate objects data memory
     size_t memsize = qQueueSize(10, sizeof(struct myobj));
     void *datamem = malloc(memsize);

     // for static data memory use can use this way
     // char datamem[NNN];

     // initialize queue
     Q_QUEUE queue;
     if(qQueueInit(&queue, datamem, memsize, sizeof(struct myobj)) == 0) {
       printf("Can't initialize queue.\n");
       return -1;
     }

     // 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(qQueuePush(&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(qQueuePopFirst(&queue, &pop) == false) break;
       printf("PopFirst : %d, %s\n", pop.integer, pop.string);

       if(qQueuePopLast(&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

Function Documentation

size_t qQueueSize ( int  max,
size_t  objsize 
)

Get how much memory is needed for N objects.

Parameters:
max a number of maximum internal slots
objsize size of queuing object
Returns:
memory size needed
Note:
This is useful when you decide how much memory(shared-memory) required for N object entries.

int qQueueInit ( Q_QUEUE queue,
void *  datamem,
size_t  datamemsize,
size_t  objsize 
)

Initialize queue.

Parameters:
queue a pointer of Q_QUEUE
datamem a pointer of data memory
datamemsize size of datamem
objsize size of queuing object
Returns:
maximum number of queuing objects
     // case of dynamic data memory
     size_t memsize = qQueueSize(10, sizeof(struct myobj));
     void *datamem = malloc(memsize);
     Q_QUEUE queue;
     if(qQueueInit(&queue, datamem, memsize, sizeof(int)) == 0) {
       printf("Can't initialize queue.\n");
       return -1;
     }

     // case of static data memory
     char datamem[1024];
     Q_QUEUE queue;
     if(qQueueInit(&queue, datamem, sizeof(datamem), sizeof(int)) == 0) {
       printf("Can't initialize queue.\n");
       return -1;
     }

bool qQueueClear ( Q_QUEUE queue  ) 

Reset 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.

bool qQueuePush ( Q_QUEUE queue,
const void *  object 
)

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

bool qQueuePopFirst ( Q_QUEUE queue,
void *  object 
)

Pop first pushed object from queue.

Parameters:
queue a pointer of Q_QUEUE
object popped objected will be stored at this object pointer
Returns:
true if successful, otherwise(queue empty or not initialized) returns false
Note:
Can be used for FIFO implementation

bool qQueuePopLast ( Q_QUEUE queue,
void *  object 
)

Pop last pushed object from queue.

Parameters:
queue a pointer of Q_QUEUE
object popped objected will be stored at this object pointer
Returns:
true if successful, otherwise(queue empty or not initialized) returns false
Note:
Can be used for STACK implementation

bool qQueueStatus ( Q_QUEUE queue,
int *  used,
int *  max 
)

Get queue internal status.

Parameters:
queue a pointer of Q_QUEUE
used if not NULL, a number of pushed objects will be stored
max if not NULL, the maximum number of pushable objects(queue size) will be stored
Returns:
true if successful, otherwise returns false


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