threadapi.h

00001 // Copyright (c) Microsoft. All rights reserved.
00002 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
00003 
00004 /** @file threadapi.h
00005  *  @brief   This module implements support for creating new threads,
00006  *           terminating threads and sleeping threads.
00007  */
00008 
00009 #ifndef THREADAPI_H
00010 #define THREADAPI_H
00011 
00012 #ifdef __cplusplus
00013 extern "C" {
00014 #endif
00015 
00016 #include "azure_c_shared_utility/macro_utils.h"
00017 #include "azure_c_shared_utility/umock_c_prod.h"
00018     
00019 typedef int(*THREAD_START_FUNC)(void *);
00020 
00021 #define THREADAPI_RESULT_VALUES \
00022     THREADAPI_OK,               \
00023     THREADAPI_INVALID_ARG,      \
00024     THREADAPI_NO_MEMORY,        \
00025     THREADAPI_ERROR
00026 
00027 /** @brief Enumeration specifying the possible return values for the APIs in
00028  *         this module.
00029  */
00030 DEFINE_ENUM(THREADAPI_RESULT, THREADAPI_RESULT_VALUES);
00031 
00032 typedef void* THREAD_HANDLE;
00033 
00034 /**
00035  * @brief   Creates a thread with the entry point specified by the @p func
00036  *          argument.
00037  *
00038  * @param   threadHandle    The handle to the new thread is returned in this
00039  *                          pointer.
00040  * @param   func            A function pointer that indicates the entry point
00041  *                          to the new thread.
00042  * @param   arg             A void pointer that must be passed to the function
00043  *                          pointed to by @p func.
00044  *
00045  * @return  @c THREADAPI_OK if the API call is successful or an error
00046  *          code in case it fails.
00047  */
00048 MOCKABLE_FUNCTION(, THREADAPI_RESULT, ThreadAPI_Create, THREAD_HANDLE*, threadHandle, THREAD_START_FUNC, func, void*, arg);
00049 
00050 /**
00051  * @brief   Blocks the calling thread by waiting on the thread identified by
00052  *          the @p threadHandle argument to complete.
00053  *
00054  * @param   threadHandle    The handle of the thread to wait for completion.
00055  * @param   res             The result returned by the thread which is passed
00056  *                          to the ::ThreadAPI_Exit function.
00057  *
00058  *          When the @p threadHandle thread completes, all resources associated
00059  *          with the thread must be released and the thread handle will no
00060  *          longer be valid.
00061  * 
00062  * @return  @c THREADAPI_OK if the API call is successful or an error
00063  *          code in case it fails.
00064  */
00065 MOCKABLE_FUNCTION(, THREADAPI_RESULT, ThreadAPI_Join, THREAD_HANDLE, threadHandle, int*, res);
00066 
00067 /**
00068  * @brief   This function is called by a thread when the thread exits.
00069  *
00070  * @param   res     An integer that represents the exit status of the thread.
00071  *              
00072  *          This function is called by a thread when the thread exits in order
00073  *          to return a result value to the caller of the ::ThreadAPI_Join
00074  *          function. The @p res value must be copied into the @p res out
00075  *          argument passed to the ::ThreadAPI_Join function.
00076  */
00077 MOCKABLE_FUNCTION(, void, ThreadAPI_Exit, int, res);
00078 
00079 /**
00080  * @brief   Sleeps the current thread for the given number of milliseconds.
00081  *
00082  * @param   milliseconds    The number of milliseconds to sleep.
00083  */
00084 MOCKABLE_FUNCTION(, void, ThreadAPI_Sleep, unsigned int, milliseconds);
00085 
00086 #ifdef __cplusplus
00087 }
00088 #endif
00089 
00090 #endif /* THREADAPI_H */