| 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. **]** |