v1.1: controlling queue allocation succesfulness

Author: SMFSW

Doxyfile

@@ -38,13 +38,13 @@ PROJECT_NAME           = cQueue
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.0
+PROJECT_NUMBER         = 1.1
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "Queue handling library"
+PROJECT_BRIEF          = "Queue handling library (written in plain c)"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -1617,7 +1617,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = NO
+GENERATE_LATEX         = YES
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1727,7 +1727,7 @@ LATEX_EXTRA_FILES      =
 # The default value is: YES.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PDF_HYPERLINKS         = NO
+PDF_HYPERLINKS         = YES
 
 # If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
 # the PDF file directly from the LaTeX files. Set this option to YES, to get a
@@ -2010,7 +2010,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2051,7 +2051,8 @@ INCLUDE_FILE_PATTERNS  = *.h
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
 PREDEFINED             = ARDUINO=10506 \
-                         DOXY=1
+                         DOXY=1 \
+                         __attribute__(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

Release Notes.txt renamed to Release Notes.md

@@ -10,5 +10,9 @@ Feel free to share your thoughts @ [email protected] about:
 
 ** Actual:
 
+v1.1	16 August 2017:
+- Queue init function now returns queue address (enabling check for queue allocation success)
+- q_pull & q_flush alias created for earlier versions and purists respectively
+
 v1.0	14 July 2017:
 - First release

cQueue_v1_1.pdf

@@ -13,6 +13,7 @@ Queue_t	KEYWORD1
 #######################################
 q_init	KEYWORD2
 q_clean	KEYWORD2
+q_flush	KEYWORD2
 q_isEmpty	KEYWORD2
 q_isFull	KEYWORD2
 q_nbRecs	KEYWORD2

keywords.txt

@@ -1,5 +1,5 @@
 name=cQueue
-version=1.0
+version=1.1
 author=SMFSW <[email protected]>
 maintainer=SMFSW <[email protected]>
 sentence=Queue handling library (written in plain c)

library.properties

@@ -1,7 +1,7 @@
 /*!\file cQueue.c
 ** \author SMFSW
-** \version 1.0
-** \date 2017/07/14
+** \version 1.1
+** \date 2017/08/16
 ** \copyright BSD 3-Clause License (c) 2017, SMFSW
 ** \brief Queue handling library (designed in c on STM32)
 ** \details Queue handling library (designed in c on STM32)
@@ -13,6 +13,7 @@
 
 #include "cQueue.h"
 
+#define QUEUE_INITIALIZED			0x5AA5									//!< Queue initialized control value
 
 #define INC_IDX(ctr, end, start)	if (ctr < (end-1))	{ ctr++; }		\
 									else				{ ctr = start; }	//!< Increments buffer index \b cnt rolling back to \b start when limit \b end is reached
@@ -21,24 +22,25 @@
 									else				{ ctr = end-1; }	//!< Decrements buffer index \b cnt rolling back to \b end when limit \b start is reached
 
 
-void q_init(Queue_t * q, uint16_t size_rec, uint16_t nb_recs, QueueType type, bool overwrite)
+void * q_init(Queue_t * q, uint16_t size_rec, uint16_t nb_recs, QueueType type, bool overwrite)
 {
 	q->rec_nb = nb_recs;
 	q->rec_sz = size_rec;
 	q->impl = type;
 	q->ovw = overwrite;
 
-	if (q->init == 0x5AA5)	{ q_kill(q); }	// Free existing data (if any)
+	q_kill(q);	// Free existing data (if any)
 	q->queue = (uint8_t *) malloc(nb_recs * size_rec);
-
-	q->init = 0x5AA5;
-
+	if (q->queue == NULL)	{ return 0; }	// Return here if Queue not allocated
+	q->init = QUEUE_INITIALIZED;
 	q_clean(q);
+
+	return q->queue;	// return NULL when queue not allocated, Queue address otherwise
 }
 
 void q_kill(Queue_t * q)
 {
-	free(q->queue);
+	if (q->init == QUEUE_INITIALIZED)	{ free(q->queue); }	// Free existing data (if already initialized)
 }
 
 

src/cQueue.c

@@ -1,7 +1,7 @@
 /*!\file cQueue.h
 ** \author SMFSW
-** \version 1.0
-** \date 2017/07/14
+** \version 1.1
+** \date 2017/08/16
 ** \copyright BSD 3-Clause License (c) 2017, SMFSW
 ** \brief Queue handling library (designed in c on STM32)
 ** \details Queue handling library (designed in c on STM32)
@@ -39,24 +39,28 @@ typedef struct Queue_t {
 } Queue_t;
 
 
-/*!	\brief Queue constructor
-**	\param [in] q - pointer of queue to handle
+#define q_init_def(q, sz)	q_init(q, sz, 20, FIFO, false)	//!< Some kind of average default for queue initialization
+
+#define q_pull				q_pop							//!< As pull was already used in SMFSW libs, alias is made to keep compatibility with earlier versions
+#define q_flush				q_clean							//!< As flush is a common keyword, alias is made to empty queue
+
+/*!	\brief Queue initialization
+**	\param [in,out] q - pointer of queue to handle
 **	\param [in] size_rec - size of a record in the queue
 **	\param [in] nb_recs - number of records in the queue
 **	\param [in] type - Queue implementation type: FIFO, LIFO
 **	\param [in] overwrite - Overwrite previous records when queue is full
-**	\return nothing
+**	\return NULL when allocation not possible, Queue tab address when successful
 **/
-void q_init(Queue_t * q, uint16_t size_rec, uint16_t nb_recs, QueueType type, bool overwrite);
-
-#define q_init_def(q, sz)	q_init(q, sz, 20, FIFO, false)
+void * q_init(Queue_t * q, uint16_t size_rec, uint16_t nb_recs, QueueType type, bool overwrite);
 
 /*!	\brief Queue desructor: release dynamically allocated queue
-**	\param [in] q - pointer of queue to handle
+**	\param [in,out] q - pointer of queue to handle
 **/
 void q_kill(Queue_t * q);
 
 /*!	\brief Clean queue, restarting from empty queue
+**	\param [in,out] q - pointer of queue to handle
 **/
 void q_clean(Queue_t * q);
 
@@ -89,7 +93,7 @@ inline uint16_t __attribute__((always_inline)) q_nbRecs(Queue_t * q) {
 }
 
 /*!	\brief Push record to queue
-**	\param [in] q - pointer of queue to handle
+**	\param [in,out] q - pointer of queue to handle
 **	\param [in] record - pointer to record to be pushed into queue
 **	\return Push status
 **	\retval true if succefully pushed into queue
@@ -116,13 +120,14 @@ bool q_pop(Queue_t * q, void * record);
 bool q_peek(Queue_t * q, void * record);
 
 	/*!	\brief Drop current record from queue
-	**	\param [in] q - pointer of queue to handle
+	**	\param [in,out] q - pointer of queue to handle
 	**	\return drop status
 	**	\retval true if succefully dropped from queue
 	**	\retval false if queue is empty
 	**/
 bool q_drop(Queue_t * q);
 
+
 #ifdef __cplusplus
 }
 #endif