[388] | 1 | // Copyright (c) Microsoft. All rights reserved.
|
---|
| 2 | // Licensed under the MIT license. See LICENSE file in the project root for full license information.
|
---|
| 3 |
|
---|
| 4 | /** @file threadapi.h
|
---|
| 5 | * @brief This module implements support for creating new threads,
|
---|
| 6 | * terminating threads and sleeping threads.
|
---|
| 7 | */
|
---|
| 8 |
|
---|
| 9 | #ifndef THREADAPI_H
|
---|
| 10 | #define THREADAPI_H
|
---|
| 11 |
|
---|
| 12 | #include "azure_c_shared_utility/macro_utils.h"
|
---|
| 13 | #include "azure_c_shared_utility/umock_c_prod.h"
|
---|
| 14 |
|
---|
| 15 | #ifdef __cplusplus
|
---|
| 16 | extern "C" {
|
---|
| 17 | #endif
|
---|
| 18 |
|
---|
| 19 | typedef int(*THREAD_START_FUNC)(void *);
|
---|
| 20 |
|
---|
| 21 | #define THREADAPI_RESULT_VALUES \
|
---|
| 22 | THREADAPI_OK, \
|
---|
| 23 | THREADAPI_INVALID_ARG, \
|
---|
| 24 | THREADAPI_NO_MEMORY, \
|
---|
| 25 | THREADAPI_ERROR
|
---|
| 26 |
|
---|
| 27 | /** @brief Enumeration specifying the possible return values for the APIs in
|
---|
| 28 | * this module.
|
---|
| 29 | */
|
---|
| 30 | MU_DEFINE_ENUM(THREADAPI_RESULT, THREADAPI_RESULT_VALUES);
|
---|
| 31 |
|
---|
| 32 | typedef void* THREAD_HANDLE;
|
---|
| 33 |
|
---|
| 34 | /**
|
---|
| 35 | * @brief Creates a thread with the entry point specified by the @p func
|
---|
| 36 | * argument.
|
---|
| 37 | *
|
---|
| 38 | * @param threadHandle The handle to the new thread is returned in this
|
---|
| 39 | * pointer.
|
---|
| 40 | * @param func A function pointer that indicates the entry point
|
---|
| 41 | * to the new thread.
|
---|
| 42 | * @param arg A void pointer that must be passed to the function
|
---|
| 43 | * pointed to by @p func.
|
---|
| 44 | *
|
---|
| 45 | * @return @c THREADAPI_OK if the API call is successful or an error
|
---|
| 46 | * code in case it fails.
|
---|
| 47 | */
|
---|
| 48 | MOCKABLE_FUNCTION(, THREADAPI_RESULT, ThreadAPI_Create, THREAD_HANDLE*, threadHandle, THREAD_START_FUNC, func, void*, arg);
|
---|
| 49 |
|
---|
| 50 | /**
|
---|
| 51 | * @brief Blocks the calling thread by waiting on the thread identified by
|
---|
| 52 | * the @p threadHandle argument to complete.
|
---|
| 53 | *
|
---|
| 54 | * @param threadHandle The handle of the thread to wait for completion.
|
---|
| 55 | * @param res The result returned by the thread which is passed
|
---|
| 56 | * to the ::ThreadAPI_Exit function.
|
---|
| 57 | *
|
---|
| 58 | * When the @p threadHandle thread completes, all resources associated
|
---|
| 59 | * with the thread must be released and the thread handle will no
|
---|
| 60 | * longer be valid.
|
---|
| 61 | *
|
---|
| 62 | * @return @c THREADAPI_OK if the API call is successful or an error
|
---|
| 63 | * code in case it fails.
|
---|
| 64 | */
|
---|
| 65 | MOCKABLE_FUNCTION(, THREADAPI_RESULT, ThreadAPI_Join, THREAD_HANDLE, threadHandle, int*, res);
|
---|
| 66 |
|
---|
| 67 | /**
|
---|
| 68 | * @brief This function is called by a thread when the thread exits.
|
---|
| 69 | *
|
---|
| 70 | * @param res An integer that represents the exit status of the thread.
|
---|
| 71 | *
|
---|
| 72 | * This function is called by a thread when the thread exits in order
|
---|
| 73 | * to return a result value to the caller of the ::ThreadAPI_Join
|
---|
| 74 | * function. The @p res value must be copied into the @p res out
|
---|
| 75 | * argument passed to the ::ThreadAPI_Join function.
|
---|
| 76 | */
|
---|
| 77 | MOCKABLE_FUNCTION(, void, ThreadAPI_Exit, int, res);
|
---|
| 78 |
|
---|
| 79 | /**
|
---|
| 80 | * @brief Sleeps the current thread for the given number of milliseconds.
|
---|
| 81 | *
|
---|
| 82 | * @param milliseconds The number of milliseconds to sleep.
|
---|
| 83 | */
|
---|
| 84 | MOCKABLE_FUNCTION(, void, ThreadAPI_Sleep, unsigned int, milliseconds);
|
---|
| 85 |
|
---|
| 86 | #ifdef __cplusplus
|
---|
| 87 | }
|
---|
| 88 | #endif
|
---|
| 89 |
|
---|
| 90 | #endif /* THREADAPI_H */
|
---|