Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/threadapi_and_sleep_requirements.md

raw
1 # threadapi and sleep
2
3 ## Overview
4
5 This document defines the behavior of the Azure IoT's **sleep** and **threadapi** adapters. These two
6 adapters are specifed together because they are declared in the same
7 [threadapi.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/threadapi.h)
8 header file.
9
10 The _sleep_ and _threadapi_ adapters are related because they share a header file and they
11 both deal with thread functionality, but
12 they are described as distinct adapters in these documents because the _sleep_ adapter is mandatory for
13 correct SDK operation, while the _threadapi_ adapter is optional.
14
15 ## References
16
17 [Azure IoT porting guide](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/porting_guide.md)<br/>
18 [threadapi.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/threadapi.h)
19
20 ## Exposed API
21
22 The _threadapi_ adapter uses these types specified in threadapi.h:
23 ```
24 typedef void* THREAD_HANDLE;
25
26 typedef enum
27 {
28 THREADAPI_OK,
29 THREADAPI_INVALID_ARG,
30 THREADAPI_NO_MEMORY,
31 THREADAPI_ERROR,
32 } THREADAPI_RESULT;
33 ```
34 ## sleep Adapter
35
36 ### ThreadAPI_Sleep
37 The _sleep_ adapter is a single exposed function, `ThreadAPI_Sleep`. This function is required for correct SDK
38 operation.
39
40 ```c
41 void ThreadAPI_Sleep(unsigned int milliseconds);
42 ```
43
44 **SRS_THREADAPI_30_001: [** ThreadAPI_Sleep shall suspend the thread for at least the supplied value of `milliseconds`. **]**
45
46 ## threadapi Adapter
47
48 ### ThreadAPI_Create
49
50 Creates a thread with an entry point specified by the `func` argument. The concrete type of the
51 `void* THREAD_HANDLE` is at the discretion of the developer.
52
53 ```c
54 THREADAPI_RESULT ThreadAPI_Create(THREAD_HANDLE* threadHandle, THREAD_START_FUNC func, void* arg);
55 ```
56
57 **SRS_THREADAPI_30_010: [** If the **threadapi** adapter is not implemented, `ThreadAPI_Create` shall return `THREADAPI_ERROR`. **]**
58
59 **SRS_THREADAPI_30_011: [** If `threadHandle` is NULL `ThreadAPI_Create` shall return `THREADAPI_INVALID_ARG`. **]**
60
61 **SRS_THREADAPI_30_012: [** If `func` is NULL `ThreadAPI_Create` shall return `THREADAPI_INVALID_ARG`. **]**
62
63 **SRS_THREADAPI_30_013: [** If `ThreadAPI_Create` is unable to create a thread it shall return `THREADAPI_ERROR` or `THREADAPI_NO_MEMORY`, whichever seems more appropriate. **]**
64
65 **SRS_THREADAPI_30_014: [** On success, `ThreadAPI_Create` shall return the created thread object in `threadHandle`. **]**
66
67 **SRS_THREADAPI_30_015: [** On success, `ThreadAPI_Create` shall return `THREADAPI_OK`. **]**
68
69
70 ### ThreadAPI_Join
71
72 Waits for the thread identified by the `threadHandle` argument to complete. When the
73 `threadHandle` thread completes, all resources associated with the thread must be released and
74 the thread handle will no longer be valid.
75
76 ```c
77 THREADAPI_RESULT ThreadAPI_Join(THREAD_HANDLE threadHandle, int* result);
78 ```
79 **SRS_THREADAPI_30_020: [** If the **threadapi** adapter is not implemented, `ThreadAPI_Join` shall return `THREADAPI_ERROR`. **]**
80
81 **SRS_THREADAPI_30_021: [** If `threadHandle` is NULL `ThreadAPI_Join` shall return `THREADAPI_INVALID_ARG`. **]**
82
83 **SRS_THREADAPI_30_022: [** If `ThreadAPI_Join` fails it shall return `THREADAPI_ERROR`. **]**
84
85 **SRS_THREADAPI_30_023: [** On success, `ThreadAPI_Join` shall wait for the thread identified by the `threadHandle` argument to complete. **]**
86
87 **SRS_THREADAPI_30_024: [** On success, all resources associated with the thread shall be released. **]**
88
89 **SRS_THREADAPI_30_025: [** On success, if `result` is non-NULL then the result of the `THREAD_START_FUNC` shall be returned in `result`. **]**
90
91 **SRS_THREADAPI_30_026: [** On success, `ThreadAPI_Join` shall return `THREADAPI_OK`. **]**
92
93 ### ThreadAPI_Exit
94
95 This function is called by the `THREAD_START_FUNC` when it exits. If another thread has called
96 `ThreadAPI_Join` then that thread will be unblocked when `ThreadAPI_Exit` is called.
97
98 The implementation must maintain the relationship between the
99 `THREAD_HANDLE` passed into `ThreadAPI_Join` and the running thread so that
100 `ThreadAPI_Exit` unblocks the correct waiting thread when when more than one `THREAD_HANDLE`
101 has been created. This relationship will need to be maintained in thread-local storage
102 or the equivalent; the thread function cannot be used for disambiguation
103 because there is no guarantee that multiple threads are not using the same thread function.
104
105
106 ```c
107 void ThreadAPI_Exit(int result);
108 ```
109 For this `ThreadAPI_Exit` specification, the phrase _"associated `ThreadAPI_Join`"_ means a
110 `ThreadAPI_Join` which was provided with the same `THREAD_HANDLE` parameter
111 that was returned during the creation of the thread from which `ThreadAPI_Exit` was called.
112
113 **SRS_THREADAPI_30_030: [** If the **threadapi** adapter is not implemented, `ThreadAPI_Exit` shall do nothing. **]**
114
115 **SRS_THREADAPI_30_031: [** If another thread has made an _associated `ThreadAPI_Join`_ call, then that thread shall be unblocked when `ThreadAPI_Exit` is called. **]**
116
117 **SRS_THREADAPI_30_032: [** The `result` parameter supplied to `ThreadAPI_Exit` shall be returned in the `result` parameter of the _associated `ThreadAPI_Join`_ call. **]**