Testing, examples, interface changes

- Added unit testing with check
- Added improved makefiles
- queue_handle_t -> queue_handle to be a little more POSIX compliant (names ending in _t are reserved) - even though queue_t still ends in _t (i aim to change when finding a suitable name for it)
- Readme updates
- Project restructure

Author: Alex Young

.gitignore

@@ -1 +1,2 @@
-main
+.DS_Store
+.out

Makefile

@@ -1,5 +1,9 @@
-main: main.c queue.h
-	gcc -std=c99 main.c -o main
+default: check examples
 
-clean:
-	rm main
+check:
+	$(MAKE) -C tests $@
+
+examples:
+	$(MAKE) -C examples
+
+.PHONY: default check examples

README.md

@@ -4,25 +4,34 @@ A type-agnostic header-only macro-based struct queue implementation in C.
 
 ## Usage
 
-To create a queueable struct, include the `queue_handle_t qh` member in your struct.
+To create a queueable struct, include the `queue_handle_t qh` member in your
+struct.
 
-Before using QUEUE_PUSH, ensure that the queue struct is set to NULL, this is the only initialisation that needs to be done.
+Before using QUEUE_PUSH, ensure that the queue struct is set to NULL, this is
+the only initialisation that needs to be done.
 
 This queue implementation is not thread safe.
 
-Freeing the queue does not free every element in the queue if they have been dynamically allocated. This has to be done by popping all the elements in the queue and freeing them manually.
+Freeing the queue does not free every element in the queue if they have been
+dynamically allocated. This has to be done by popping all the elements in the
+queue and freeing them manually.
+
+Pushing the same element (at the same address) into the queue is not supported.
+This is because the 'next' member of the queue's queue_handle will be
+overwitten. This will case undefined behaviour when pushing or popping to or
+from the queue (see commented out test case).
 
 ```c
 #include <stdio.h>
 #include "queue.h"
 
 struct msg {
 	char *content;
-	queue_handle_t qh;
+	queue_handle qh;
 }
 
 int main(void) {
-	struct msgs *queue;
+	struct msg *queue;
 	struct msg m1, m2;
 
 	queue = NULL;

examples/Makefile

@@ -0,0 +1,3 @@
+default:
+
+.PHONY: default

main.c renamed to examples/main.c

@@ -0,0 +1,26 @@
+#include <stdio.h>
+#include "queue.h"
+
+struct msg {
+	char *content;
+	queue_handle qh;
+}
+
+int main(void) {
+	struct msg *queue;
+	struct msg m1, m2;
+
+	queue = NULL;
+
+	m1.content = "abc";
+	QUEUE_PUSH(queue, &m1);
+
+	printf("queue size: %d\n", QUEUE_SIZE(queue)); // queue size: 1
+
+	QUEUE_POP(queue, &m2);
+	printf("m2 content: %s\n", m2.content); // m2 content: abc
+
+	QUEUE_FREE(queue);
+
+	return 0;
+}

examples/readme_example.c

@@ -6,17 +6,15 @@
 typedef struct {
 	void *front;
 	void *back;
-
-	void *frontqh;
+	void *frontqh; // TODO: remove?
 	void *backqh;
-
 	unsigned int size;
 } queue_t;
 
 typedef struct queue_handle {
 	queue_t *q;
 	void *next;
-} queue_handle_t;
+} queue_handle;
 
 #define QUEUE_PUSH(queue, element)											\
 	do {																	\
@@ -31,8 +29,7 @@ typedef struct queue_handle {
 			(queue) = (element);											\
 		} else {															\
 			queue_t *q = (queue)->qh.q;										\
-			queue_handle_t *backqh = q->backqh;								\
-			queue_handle_t *frontqh = q->frontqh;							\
+			queue_handle *backqh = q->backqh;								\
 																			\
 			(element)->qh.q = q;											\
 			(element)->qh.next = NULL;										\
@@ -43,8 +40,6 @@ typedef struct queue_handle {
 			backqh = &((element)->qh);										\
 																			\
 			q->backqh = backqh;												\
-			q->frontqh = frontqh;											\
-																			\
 		}																	\
 		(queue)->qh.q->size++;												\
 	} while (0)
@@ -66,7 +61,9 @@ typedef struct queue_handle {
 
 #define QUEUE_FREE(queue)													\
 	do {																	\
-		free(queue->qh.q);													\
+		if (queue && queue->qh.q) {											\
+			free(queue->qh.q);												\
+		}																	\
 	} while (0)
 
 #endif /* QUEUE_H_ */

queue.h renamed to src/queue.h

@@ -0,0 +1,11 @@
+CC = gcc
+STD = -std=c99
+CFLAGS = $(STD) -I ../src
+LIBS = -lcheck
+
+check: check_queue.c ../src/queue.h
+	$(CC) $(CFLAGS) check_queue.c -o check_queue $(LIBS)
+	./check_queue
+	rm check_queue
+
+.PHONY: check