4.3 KiB
execution_engine_win32 requirements
Overview
execution_engine_win32 is a module that implements the execution engine supporting threadpool, asynchronous socket APIs and asynchronous file APIs for Windows.
Design
execution_engine_win32 is backed by a Win32 threadpool (PTP_POOL).
Exposed API
execution_engine_win32 implements the execution_engine API and additionally exposes the following API:
typedef struct EXECUTION_ENGINE_PARAMETERS_TAG
{
uint32_t min_thread_count;
uint32_t max_thread_count;
} EXECUTION_ENGINE_PARAMETERS;
#define DEFAULT_MIN_THREAD_COUNT 4
#define DEFAULT_MAX_THREAD_COUNT 0 // no max thread count
MOCKABLE_FUNCTION(, EXECUTION_ENGINE_HANDLE, execution_engine_create, void*, execution_engine_parameters);
MOCKABLE_FUNCTION(, void, execution_engine_dec_ref, EXECUTION_ENGINE_HANDLE, execution_engine);
MOCKABLE_FUNCTION(, void, execution_engine_inc_ref, EXECUTION_ENGINE_HANDLE, execution_engine);
MOCKABLE_FUNCTION(, PTP_POOL, execution_engine_win32_get_threadpool, EXECUTION_ENGINE_HANDLE, execution_engine);
execution_engine_create
MOCKABLE_FUNCTION(, EXECUTION_ENGINE_HANDLE, execution_engine_create, void*, execution_engine_parameters);
execution_engine_create creates an execution engine.
SRS_EXECUTION_ENGINE_WIN32_01_001: [ execution_engine_create shall allocate a new execution engine and on success shall return a non-NULL handle. ]
SRS_EXECUTION_ENGINE_WIN32_01_011: [ If execution_engine_parameters is NULL, execution_engine_create shall use the defaults DEFAULT_MIN_THREAD_COUNT and DEFAULT_MAX_THREAD_COUNT as parameters. ]
SRS_EXECUTION_ENGINE_WIN32_01_002: [ execution_engine_parameters shall be interpreted as EXECUTION_ENGINE_PARAMETERS. ]
SRS_EXECUTION_ENGINE_WIN32_01_003: [ execution_engine_create shall call CreateThreadpool to create the Win32 threadpool. ]
SRS_EXECUTION_ENGINE_WIN32_01_004: [ execution_engine_create shall set the minimum number of threads to the min_thread_count field of execution_engine_parameters. ]
SRS_EXECUTION_ENGINE_WIN32_01_005: [ execution_engine_create shall set the maximum number of threads to the max_thread_count field of execution_engine_parameters. ]
SRS_EXECUTION_ENGINE_WIN32_01_012: [ If max_thread_count is 0, execution_engine_create shall not set the maximum thread count. ]
SRS_EXECUTION_ENGINE_WIN32_01_013: [ If max_thread_count is non-zero, but less than min_thread_count, execution_engine_create shall fail and return NULL. ]
SRS_EXECUTION_ENGINE_WIN32_01_006: [ If any error occurs, execution_engine_create shall fail and return NULL. ]
execution_engine_dec_ref
MOCKABLE_FUNCTION(, void, execution_engine_dec_ref, EXECUTION_ENGINE_HANDLE, execution_engine);
execution_engine_dec_ref decrements the ref count and frees all resources associated with execution_engine if needed.
SRS_EXECUTION_ENGINE_WIN32_01_007: [ If execution_engine is NULL, execution_engine_dec_ref shall return. ]
SRS_EXECUTION_ENGINE_WIN32_03_001: [ Otherwise execution_engine_dec_ref shall decrement the refcount. ]
SRS_EXECUTION_ENGINE_WIN32_03_002: [ If the refcount is zero execution_engine_dec_ref shall close the threadpool. ]
MOCKABLE_FUNCTION(, void, execution_engine_inc_ref, EXECUTION_ENGINE_HANDLE, execution_engine);
execution_engine_inc_ref increments the ref count on the execution_engine.
SRS_EXECUTION_ENGINE_WIN32_03_003: [ If execution_engine is NULL then execution_engine_inc_ref shall return. ]
SRS_EXECUTION_ENGINE_WIN32_03_004: [ Otherwise execution_engine_inc_ref shall increment the reference count for execution_engine. ]
execution_engine_win32_get_threadpool
MOCKABLE_FUNCTION(, PTP_POOL, execution_engine_win32_get_threadpool, EXECUTION_ENGINE_HANDLE, execution_engine);
execution_engine_win32_get_threadpool returns the underlying Win32 threadpool handle.
SRS_EXECUTION_ENGINE_WIN32_01_009: [ If execution_engine is NULL, execution_engine_win32_get_threadpool shall fail and return NULL. ]
SRS_EXECUTION_ENGINE_WIN32_01_010: [ Otherwise, execution_engine_win32_get_threadpool shall return the threadpool handle created in execution_engine_create. ]