Debian Codegraph @

src/vendor/azure-uamqp-c/devdoc/async_operation_requirements.md

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