`refcount` requirements ================ ## Overview `refcount` is a module that provides reference counting for a given structure. It wraps the structure that needs to be ref counted into another structure that contains an additional field (ref count). ## Exposed API ```c #define REFCOUNT_TYPE_CREATE(type) MU_C2(REFCOUNT_SHORT_TYPE(type), _Create)() #define REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE(type, size) MU_C2(REFCOUNT_SHORT_TYPE(type), _Create_With_Extra_Size)(size) #define REFCOUNT_TYPE_DESTROY(type, var) MU_C2(REFCOUNT_SHORT_TYPE(type), _Destroy)(var) #define DEFINE_REFCOUNT_TYPE(type) \ ... ``` ### DEFINE_REFCOUNT_TYPE **SRS_REFCOUNT_01_001: [** `DEFINE_REFCOUNT_TYPE` shall define the create/create_with_Extra_size/destroy functions for the type `type`. **]** ### REFCOUNT_TYPE_CREATE ```c REFCOUNT_TYPE_CREATE(type) ``` `REFCOUNT_TYPE_CREATE` creates a ref counted object instance. **SRS_REFCOUNT_01_002: [** `REFCOUNT_TYPE_CREATE` shall allocate memory for the type that is ref counted. **]** **SRS_REFCOUNT_01_003: [** On success it shall return a non-NULL handle to the allocated ref counted type `type`. **]** **SRS_REFCOUNT_01_004: [** If any error occurs, `REFCOUNT_TYPE_CREATE` shall return NULL. **]** ### REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE ```c REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE(type, size) ``` `REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE` creates a ref counted object instance while allocating extra memory (useful for flexible arrays). **SRS_REFCOUNT_01_005: [** `REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE` shall allocate memory for the type that is ref counted (`type`) plus extra memory enough to hold `size` bytes. **]** **SRS_REFCOUNT_01_006: [** On success it shall return a non-NULL handle to the allocated ref counted type `type`. **]** **SRS_REFCOUNT_01_007: [** If any error occurs, `REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE` shall return NULL. **]** ### REFCOUNT_TYPE_DESTROY ```c REFCOUNT_TYPE_DESTROY(type, counted_type) ``` `REFCOUNT_TYPE_DESTROY` frees the memory for a ref counted type. **SRS_REFCOUNT_01_008: [** `REFCOUNT_TYPE_DESTROY` shall free the memory allocated by `REFCOUNT_TYPE_CREATE` or `REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE`. **]** **SRS_REFCOUNT_01_009: [** If `counted_type` is NULL, `REFCOUNT_TYPE_DESTROY` shall return. **]**