# `async_operation` requirements ## Overview `async_operation` is module that encapsulates an asyncronous cancellable operation. ## Exposed API ```C typedef struct ASYNC_OPERATION_INSTANCE_TAG* ASYNC_OPERATION_HANDLE; typedef void(*ASYNC_OPERATION_CANCEL_HANDLER_FUNC)(void* context); #define DEFINE_ASYNC_OPERATION_CONTEXT(type) \ struct C3(ASYNC_OPERATION_CONTEXT_, type, _TAG)(type) \ { \ ASYNC_OPERATION_CANCEL_HANDLER_FUNC async_operation_cancel_handler; \ type context; \ }; #define GET_ASYNC_OPERATION_CONTEXT(type, async_operation) \ (type*)((unsigned char*)async_operation + offsetof(type, context)) #define CREATE_ASYNC_OPERATION(type, async_operation_cancel_handler) \ async_operation_create(async_operation_cancel_handler, sizeof(type)) MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, async_operation_create, ASYNC_OPERATION_CANCEL_HANDLER_FUNC, async_operation_cancel_handler, size_t, context_size); MOCKABLE_FUNCTION(, void, async_operation_destroy, ASYNC_OPERATION_HANDLE, async_operation); MOCKABLE_FUNCTION(, int, async_operation_cancel, ASYNC_OPERATION_HANDLE, async_operation); ``` ### async_operation_create ```C MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, async_operation_create, ASYNC_OPERATION_CANCEL_HANDLER_FUNC, async_operation_cancel_handler, size_t, context_size); ``` **SRS_ASYNC_OPERATION_01_001: [** `async_operation_create` shall return a non-NULL handle to a newly created asynchronous operation instance.**]** **SRS_ASYNC_OPERATION_01_002: [** If `async_operation_cancel_handler` is NULL, `async_operation_create` shall fail and return NULL.**]** **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.**]** **SRS_ASYNC_OPERATION_01_004: [** If allocating memory for the new asynchronous operation instance fails, `async_operation_create` shall fail and return NULL.**]** ### async_operation_destroy ```C MOCKABLE_FUNCTION(, void, async_operation_destroy, ASYNC_OPERATION_HANDLE, async_operation); ``` **SRS_ASYNC_OPERATION_01_005: [** `async_operation_destroy` shall free all recources associated with the asyncronous operation instance.**]** **SRS_ASYNC_OPERATION_01_006: [** If `async_operation` is NULL, `async_operation_destroy` shall do nothing.**]** ### async_operation_cancel ```C MOCKABLE_FUNCTION(, int, async_operation_cancel, ASYNC_OPERATION_HANDLE, async_operation); ``` **SRS_ASYNC_OPERATION_01_007: [** `async_operation_cancel` shall cancel the operation by calling the cancel handler function passed to `async_operation_create`.**]** **SRS_ASYNC_OPERATION_01_008: [** On success `async_operation_cancel` shall return 0.**]** **SRS_ASYNC_OPERATION_01_009: [** If `async_operation` is NULL, `async_operation_cancel` shall fail and return a non-zero value.**]**