| 1 |
# `async_operation` requirements |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
`async_operation` is module that encapsulates an asyncronous cancellable operation. |
| 6 |
|
| 7 |
## Exposed API |
| 8 |
|
| 9 |
```C |
| 10 |
typedef struct ASYNC_OPERATION_INSTANCE_TAG* ASYNC_OPERATION_HANDLE; |
| 11 |
|
| 12 |
typedef void(*ASYNC_OPERATION_CANCEL_HANDLER_FUNC)(void* context); |
| 13 |
|
| 14 |
#define DEFINE_ASYNC_OPERATION_CONTEXT(type) \ |
| 15 |
struct C3(ASYNC_OPERATION_CONTEXT_, type, _TAG)(type) \ |
| 16 |
{ \ |
| 17 |
ASYNC_OPERATION_CANCEL_HANDLER_FUNC async_operation_cancel_handler; \ |
| 18 |
type context; \ |
| 19 |
}; |
| 20 |
|
| 21 |
#define GET_ASYNC_OPERATION_CONTEXT(type, async_operation) \ |
| 22 |
(type*)((unsigned char*)async_operation + offsetof(type, context)) |
| 23 |
|
| 24 |
#define CREATE_ASYNC_OPERATION(type, async_operation_cancel_handler) \ |
| 25 |
async_operation_create(async_operation_cancel_handler, sizeof(type)) |
| 26 |
|
| 27 |
MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, async_operation_create, ASYNC_OPERATION_CANCEL_HANDLER_FUNC, async_operation_cancel_handler, size_t, context_size); |
| 28 |
MOCKABLE_FUNCTION(, void, async_operation_destroy, ASYNC_OPERATION_HANDLE, async_operation); |
| 29 |
MOCKABLE_FUNCTION(, int, async_operation_cancel, ASYNC_OPERATION_HANDLE, async_operation); |
| 30 |
``` |
| 31 |
|
| 32 |
### async_operation_create |
| 33 |
|
| 34 |
```C |
| 35 |
MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, async_operation_create, ASYNC_OPERATION_CANCEL_HANDLER_FUNC, async_operation_cancel_handler, size_t, context_size); |
| 36 |
``` |
| 37 |
|
| 38 |
**SRS_ASYNC_OPERATION_01_001: [** `async_operation_create` shall return a non-NULL handle to a newly created asynchronous operation instance.**]** |
| 39 |
**SRS_ASYNC_OPERATION_01_002: [** If `async_operation_cancel_handler` is NULL, `async_operation_create` shall fail and return NULL.**]** |
| 40 |
**SRS_ASYNC_OPERATION_01_003: [** If `context_size` is less than the size of the `async_operation_cancel_handler` argument, `async_operation_create` shall fail and return NULL.**]** |
| 41 |
**SRS_ASYNC_OPERATION_01_004: [** If allocating memory for the new asynchronous operation instance fails, `async_operation_create` shall fail and return NULL.**]** |
| 42 |
|
| 43 |
### async_operation_destroy |
| 44 |
|
| 45 |
```C |
| 46 |
MOCKABLE_FUNCTION(, void, async_operation_destroy, ASYNC_OPERATION_HANDLE, async_operation); |
| 47 |
``` |
| 48 |
|
| 49 |
**SRS_ASYNC_OPERATION_01_005: [** `async_operation_destroy` shall free all recources associated with the asyncronous operation instance.**]** |
| 50 |
**SRS_ASYNC_OPERATION_01_006: [** If `async_operation` is NULL, `async_operation_destroy` shall do nothing.**]** |
| 51 |
|
| 52 |
### async_operation_cancel |
| 53 |
|
| 54 |
```C |
| 55 |
MOCKABLE_FUNCTION(, int, async_operation_cancel, ASYNC_OPERATION_HANDLE, async_operation); |
| 56 |
``` |
| 57 |
|
| 58 |
**SRS_ASYNC_OPERATION_01_007: [** `async_operation_cancel` shall cancel the operation by calling the cancel handler function passed to `async_operation_create`.**]** |
| 59 |
**SRS_ASYNC_OPERATION_01_008: [** On success `async_operation_cancel` shall return 0.**]** |
| 60 |
**SRS_ASYNC_OPERATION_01_009: [** If `async_operation` is NULL, `async_operation_cancel` shall fail and return a non-zero value.**]** |