source: azure_iot_hub_f767zi/trunk/azure_iot_sdk/c-utility/inc/azure_c_shared_utility/threadapi.h@ 457

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

/** @file threadapi.h
 *      @brief   This module implements support for creating new threads,
 *                       terminating threads and sleeping threads.
 */

#ifndef THREADAPI_H
#define THREADAPI_H

#include "azure_macro_utils/macro_utils.h"
#include "umock_c/umock_c_prod.h"

#ifdef __cplusplus
extern "C" {
#endif
    
typedef int(*THREAD_START_FUNC)(void *);

#define THREADAPI_RESULT_VALUES \
    THREADAPI_OK,               \
    THREADAPI_INVALID_ARG,      \
    THREADAPI_NO_MEMORY,        \
    THREADAPI_ERROR

/** @brief Enumeration specifying the possible return values for the APIs in
 *                 this module.
 */
MU_DEFINE_ENUM(THREADAPI_RESULT, THREADAPI_RESULT_VALUES);

typedef void* THREAD_HANDLE;

/**
 * @brief       Creates a thread with the entry point specified by the @p func
 *                      argument.
 *
 * @param   threadHandle        The handle to the new thread is returned in this
 *                                                      pointer.
 * @param       func                    A function pointer that indicates the entry point
 *                                                      to the new thread.
 * @param   arg                         A void pointer that must be passed to the function
 *                                                      pointed to by @p func.
 *
 * @return      @c THREADAPI_OK if the API call is successful or an error
 *                      code in case it fails.
 */
MOCKABLE_FUNCTION(, THREADAPI_RESULT, ThreadAPI_Create, THREAD_HANDLE*, threadHandle, THREAD_START_FUNC, func, void*, arg);

/**
 * @brief       Blocks the calling thread by waiting on the thread identified by
 *                      the @p threadHandle argument to complete.
 *
 * @param       threadHandle    The handle of the thread to wait for completion.
 * @param   res                         The result returned by the thread which is passed
 *                                                      to the ::ThreadAPI_Exit function.
 *
 *                      When the @p threadHandle thread completes, all resources associated
 *                      with the thread must be released and the thread handle will no
 *                      longer be valid.
 * 
 * @return      @c THREADAPI_OK if the API call is successful or an error
 *                      code in case it fails.
 */
MOCKABLE_FUNCTION(, THREADAPI_RESULT, ThreadAPI_Join, THREAD_HANDLE, threadHandle, int*, res);

/**
 * @brief       This function is called by a thread when the thread exits.
 *
 * @param       res             An integer that represents the exit status of the thread.
 *                              
 *                      This function is called by a thread when the thread exits in order
 *                      to return a result value to the caller of the ::ThreadAPI_Join
 *                      function. The @p res value must be copied into the @p res out
 *                      argument passed to the ::ThreadAPI_Join function.
 */
MOCKABLE_FUNCTION(, void, ThreadAPI_Exit, int, res);

/**
 * @brief       Sleeps the current thread for the given number of milliseconds.
 *
 * @param       milliseconds    The number of milliseconds to sleep.
 */
MOCKABLE_FUNCTION(, void, ThreadAPI_Sleep, unsigned int, milliseconds);

#ifdef __cplusplus
}
#endif

#endif /* THREADAPI_H */