Diff: internal/message_queue.h

Revision:

56:8704100b3b54

Parent:

53:e21e1e88460f

diff -r 6420ea342cd1 -r 8704100b3b54 internal/message_queue.h
--- a/internal/message_queue.h	Thu Jul 12 18:08:04 2018 -0700
+++ b/internal/message_queue.h	Tue Sep 11 11:11:47 2018 -0700
@@ -1,8 +1,8 @@
 // Copyright (c) Microsoft. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-/** @file	message_queue.h
-*	@brief	A generic message queue.
+/** @file    message_queue.h
+*    @brief    A generic message queue.
 */
 
 #ifndef MESSAGE_QUEUE_H
@@ -31,147 +31,147 @@
 DEFINE_ENUM(MESSAGE_QUEUE_RESULT, MESSAGE_QUEUE_RESULT_STRINGS);
 
 /**
-* @brief	User-provided callback invoked by MESSAGE_QUEUE back to the user when a messages completes being processed.
+* @brief    User-provided callback invoked by MESSAGE_QUEUE back to the user when a messages completes being processed.
 */
 typedef void(*MESSAGE_PROCESSING_COMPLETED_CALLBACK)(MQ_MESSAGE_HANDLE message, MESSAGE_QUEUE_RESULT result, USER_DEFINED_REASON reason, void* user_context);
 
 /**
-* @brief	Callback that MUST be invoked by PROCESS_MESSAGE_CALLBACK (user provided) to signal to MESSAGE_QUEUE that a message has been processed.
+* @brief    Callback that MUST be invoked by PROCESS_MESSAGE_CALLBACK (user provided) to signal to MESSAGE_QUEUE that a message has been processed.
 * @remarks  Besides causing MESSAGE_QUEUE to dequeue the message from its internal lists, causes MESSAGE_PROCESSING_COMPLETED_CALLBACK to be triggered.
 */
 typedef void(*PROCESS_MESSAGE_COMPLETED_CALLBACK)(MESSAGE_QUEUE_HANDLE message_queue, MQ_MESSAGE_HANDLE message, MESSAGE_QUEUE_RESULT result, USER_DEFINED_REASON reason);
 
 /**
-* @brief	User-provided callback invoked by MESSAGE_QUEUE when a messages is ready to be processed, getting internally moved from "pending" to "in-progress".
+* @brief    User-provided callback invoked by MESSAGE_QUEUE when a messages is ready to be processed, getting internally moved from "pending" to "in-progress".
 */
 typedef void(*PROCESS_MESSAGE_CALLBACK)(MESSAGE_QUEUE_HANDLE message_queue, MQ_MESSAGE_HANDLE message, PROCESS_MESSAGE_COMPLETED_CALLBACK on_process_message_completed_callback, void* user_context);
 
 typedef struct MESSAGE_QUEUE_CONFIG_TAG
 {
-	/**
-	* @brief	Function that actually process (a.k.a, e.g, sends) a message previously queued.
-	*
-	* @remarks  When MESSAGE_QUEUE is summoned to invoke @c on_process_message_callback (upon call to message_queue_do_work, when a message is moved from the pending to in-progress list),
-	*           it passes as arguments the MESSAGE_QUEUE handle and a callback function that MUST be invoked by @c on_process_message_callback once it completes.
-	*           The @c user_context passed is the same provided as argument by the upper layer on @c message_queue_add.
-	*/
-	PROCESS_MESSAGE_CALLBACK on_process_message_callback;
-	size_t max_message_enqueued_time_secs;
-	size_t max_message_processing_time_secs;
-	size_t max_retry_count;
+    /**
+    * @brief    Function that actually process (a.k.a, e.g, sends) a message previously queued.
+    *
+    * @remarks  When MESSAGE_QUEUE is summoned to invoke @c on_process_message_callback (upon call to message_queue_do_work, when a message is moved from the pending to in-progress list),
+    *           it passes as arguments the MESSAGE_QUEUE handle and a callback function that MUST be invoked by @c on_process_message_callback once it completes.
+    *           The @c user_context passed is the same provided as argument by the upper layer on @c message_queue_add.
+    */
+    PROCESS_MESSAGE_CALLBACK on_process_message_callback;
+    size_t max_message_enqueued_time_secs;
+    size_t max_message_processing_time_secs;
+    size_t max_retry_count;
 } MESSAGE_QUEUE_CONFIG;
 
 /**
-* @brief	Creates a new instance of MESSAGE_QUEUE.
+* @brief    Creates a new instance of MESSAGE_QUEUE.
 *
-* @param	config	Pointer to an @c MESSAGE_QUEUE_CONFIG structure
+* @param    config    Pointer to an @c MESSAGE_QUEUE_CONFIG structure
 *
-* @returns	A non-NULL @c MESSAGE_QUEUE_HANDLE value that is used when invoking other API functions.
+* @returns    A non-NULL @c MESSAGE_QUEUE_HANDLE value that is used when invoking other API functions.
 */
 MOCKABLE_FUNCTION(, MESSAGE_QUEUE_HANDLE,  message_queue_create, MESSAGE_QUEUE_CONFIG*, config);
 
 /**
-* @brief	Destroys an instance of MESSAGE_QUEUE, releasing all memory it allocated.
+* @brief    Destroys an instance of MESSAGE_QUEUE, releasing all memory it allocated.
 *
 * @remarks  All messages still pending to be processed and currently in-progress get bubbled up back to the upper-layer
-*           through the @c on_message_processing_completed_callback (passed on the @c MESSAGE_QUEUE_CONFIG instance) 
+*           through the @c on_message_processing_completed_callback (passed on the @c MESSAGE_QUEUE_CONFIG instance)
 *           with the @c result set as @c MESSAGE_QUEUE_CANCELLED and @c reason set to @c NULL.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 */
 MOCKABLE_FUNCTION(, void, message_queue_destroy, MESSAGE_QUEUE_HANDLE, message_queue);
 
 /**
-* @brief	Adds a new generic message to MESSAGE_QUEUE's pending list.
+* @brief    Adds a new generic message to MESSAGE_QUEUE's pending list.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @param	message A generic message to be queued and then processed (i.e., sent, consolidated, etc).
+* @param    message A generic message to be queued and then processed (i.e., sent, consolidated, etc).
 *
-* @returns	Zero if the no errors occur, non-zero otherwise.
+* @returns    Zero if the no errors occur, non-zero otherwise.
 */
 MOCKABLE_FUNCTION(, int, message_queue_add, MESSAGE_QUEUE_HANDLE, message_queue, MQ_MESSAGE_HANDLE, message, MESSAGE_PROCESSING_COMPLETED_CALLBACK, on_message_processing_completed_callback, void*, user_context);
 
 /**
-* @brief	Causes all messages in-progress to be moved back to the beginning of the pending list.
+* @brief    Causes all messages in-progress to be moved back to the beginning of the pending list.
 *
-* @remarks	If on_message_process_completed_callback is invoked for any of message not in in-progress, it is disregarded.
+* @remarks    If on_message_process_completed_callback is invoked for any of message not in in-progress, it is disregarded.
 *           Messages are queued back into the pending list in a way they will be sent first when message_queue_do_work is invoked again.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @returns	Zero if the no errors occur, non-zero otherwise.
+* @returns    Zero if the no errors occur, non-zero otherwise.
 */
 MOCKABLE_FUNCTION(, int, message_queue_move_all_back_to_pending, MESSAGE_QUEUE_HANDLE, message_queue);
 
 /**
-* @brief	Causes all messages pending to be sent and in-progress to be flushed back to the user through @c on_message_processing_completed_callback.
+* @brief    Causes all messages pending to be sent and in-progress to be flushed back to the user through @c on_message_processing_completed_callback.
 *
-* @remarks	@c on_message_processing_completed_callback gets invoked with @c result set as MESSAGE_QUEUE_CANCELLED and @c reason set to NULL.
+* @remarks    @c on_message_processing_completed_callback gets invoked with @c result set as MESSAGE_QUEUE_CANCELLED and @c reason set to NULL.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 */
 MOCKABLE_FUNCTION(, void, message_queue_remove_all, MESSAGE_QUEUE_HANDLE, message_queue);
 
 /**
-* @brief	Informs if there are messages pending to be sent and/or currently in-progress.
+* @brief    Informs if there are messages pending to be sent and/or currently in-progress.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @param	@c is_empty Set to @c true if there are any messages in pending to be sent and/or currently in-progress, @c false otherwise.
+* @param    @c is_empty Set to @c true if there are any messages in pending to be sent and/or currently in-progress, @c false otherwise.
 *
-* @remarks	The parameter @c is_empty is only set if no errors occur (like passing a NULL @c message_queue).
+* @remarks    The parameter @c is_empty is only set if no errors occur (like passing a NULL @c message_queue).
 *
-* @returns	Zero if the no errors occur, non-zero otherwise.
+* @returns    Zero if the no errors occur, non-zero otherwise.
 */
 MOCKABLE_FUNCTION(, int, message_queue_is_empty, MESSAGE_QUEUE_HANDLE, message_queue, bool*, is_empty);
 
 /**
-* @brief	Causes MESSAGE_QUEUE to go through its list of pending messages and move them to in-progress, as well as trigering retry and timeout controls.
+* @brief    Causes MESSAGE_QUEUE to go through its list of pending messages and move them to in-progress, as well as trigering retry and timeout controls.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 */
 MOCKABLE_FUNCTION(, void, message_queue_do_work, MESSAGE_QUEUE_HANDLE, message_queue);
 
 /**
-* @brief	Sets the maximum time, in seconds, a message will be within MESSAGE_QUEUE (in either pending or in-progress lists).
+* @brief    Sets the maximum time, in seconds, a message will be within MESSAGE_QUEUE (in either pending or in-progress lists).
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @param	seconds	Number of seconds to set for this timeout. A value of zero de-activates this timeout control.
+* @param    seconds    Number of seconds to set for this timeout. A value of zero de-activates this timeout control.
 *
-* @returns	Zero if the no errors occur, non-zero otherwise.
+* @returns    Zero if the no errors occur, non-zero otherwise.
 */
 MOCKABLE_FUNCTION(, int, message_queue_set_max_message_enqueued_time_secs, MESSAGE_QUEUE_HANDLE, message_queue, size_t, seconds);
 
 /**
-* @brief	Sets the maximum time, in seconds, a message will be in-progress within MESSAGE_QUEUE.
+* @brief    Sets the maximum time, in seconds, a message will be in-progress within MESSAGE_QUEUE.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @param	seconds	Number of seconds to set for this timeout. A value of zero de-activates this timeout control.
+* @param    seconds    Number of seconds to set for this timeout. A value of zero de-activates this timeout control.
 *
-* @returns	Zero if the no errors occur, non-zero otherwise.
+* @returns    Zero if the no errors occur, non-zero otherwise.
 */
 MOCKABLE_FUNCTION(, int, message_queue_set_max_message_processing_time_secs, MESSAGE_QUEUE_HANDLE, message_queue, size_t, seconds);
 
 /**
-* @brief	Sets the maximum number of times MESSAGE_QUEUE will try to re-process a message (no counting the initial attempt).
+* @brief    Sets the maximum number of times MESSAGE_QUEUE will try to re-process a message (no counting the initial attempt).
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @param	max_retry_count	The number of times MESSAGE_QUEUE will try to re-process a message.
+* @param    max_retry_count    The number of times MESSAGE_QUEUE will try to re-process a message.
 *
-* @returns	Zero if the no errors occur, non-zero otherwise.
+* @returns    Zero if the no errors occur, non-zero otherwise.
 */
 MOCKABLE_FUNCTION(, int, message_queue_set_max_retry_count, MESSAGE_QUEUE_HANDLE, message_queue, size_t, max_retry_count);
 
 /**
-* @brief	Retrieves a blob with all the options currently set in the instance of MESSAGE_QUEUE.
+* @brief    Retrieves a blob with all the options currently set in the instance of MESSAGE_QUEUE.
 *
-* @param	message_queue	A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
+* @param    message_queue    A @c MESSAGE_QUEUE_HANDLE obtained using message_queue_create.
 *
-* @returns	A non-NULL @c OPTIONHANDLER_HANDLE if no errors occur, or NULL otherwise.
+* @returns    A non-NULL @c OPTIONHANDLER_HANDLE if no errors occur, or NULL otherwise.
 */
 MOCKABLE_FUNCTION(, OPTIONHANDLER_HANDLE, message_queue_retrieve_options, MESSAGE_QUEUE_HANDLE, message_queue);