The qDecoder Project: C/C++ Library

- Main Page
- Data Structures
- Files

- File List
- Globals

# 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]