Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/inc/azure_c_shared_utility/threadapi.h

raw
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_macro_utils/macro_utils.h"
13 #include "umock_c/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 */