| 1 |
`refcount` requirements |
| 2 |
================ |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
`refcount` is a module that provides reference counting for a given structure. |
| 7 |
It wraps the structure that needs to be ref counted into another structure that contains an additional field (ref count). |
| 8 |
|
| 9 |
## Exposed API |
| 10 |
|
| 11 |
```c |
| 12 |
#define REFCOUNT_TYPE_CREATE(type) MU_C2(REFCOUNT_SHORT_TYPE(type), _Create)() |
| 13 |
#define REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE(type, size) MU_C2(REFCOUNT_SHORT_TYPE(type), _Create_With_Extra_Size)(size) |
| 14 |
#define REFCOUNT_TYPE_DESTROY(type, var) MU_C2(REFCOUNT_SHORT_TYPE(type), _Destroy)(var) |
| 15 |
|
| 16 |
#define DEFINE_REFCOUNT_TYPE(type) \ |
| 17 |
... |
| 18 |
``` |
| 19 |
|
| 20 |
### DEFINE_REFCOUNT_TYPE |
| 21 |
|
| 22 |
**SRS_REFCOUNT_01_001: [** `DEFINE_REFCOUNT_TYPE` shall define the create/create_with_Extra_size/destroy functions for the type `type`. **]** |
| 23 |
|
| 24 |
### REFCOUNT_TYPE_CREATE |
| 25 |
|
| 26 |
```c |
| 27 |
REFCOUNT_TYPE_CREATE(type) |
| 28 |
``` |
| 29 |
|
| 30 |
`REFCOUNT_TYPE_CREATE` creates a ref counted object instance. |
| 31 |
|
| 32 |
**SRS_REFCOUNT_01_002: [** `REFCOUNT_TYPE_CREATE` shall allocate memory for the type that is ref counted. **]** |
| 33 |
|
| 34 |
**SRS_REFCOUNT_01_003: [** On success it shall return a non-NULL handle to the allocated ref counted type `type`. **]** |
| 35 |
|
| 36 |
**SRS_REFCOUNT_01_004: [** If any error occurs, `REFCOUNT_TYPE_CREATE` shall return NULL. **]** |
| 37 |
|
| 38 |
### REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE |
| 39 |
|
| 40 |
```c |
| 41 |
REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE(type, size) |
| 42 |
``` |
| 43 |
|
| 44 |
`REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE` creates a ref counted object instance while allocating extra memory (useful for flexible arrays). |
| 45 |
|
| 46 |
**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. **]** |
| 47 |
|
| 48 |
**SRS_REFCOUNT_01_006: [** On success it shall return a non-NULL handle to the allocated ref counted type `type`. **]** |
| 49 |
|
| 50 |
**SRS_REFCOUNT_01_007: [** If any error occurs, `REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE` shall return NULL. **]** |
| 51 |
|
| 52 |
### REFCOUNT_TYPE_DESTROY |
| 53 |
|
| 54 |
```c |
| 55 |
REFCOUNT_TYPE_DESTROY(type, counted_type) |
| 56 |
``` |
| 57 |
|
| 58 |
`REFCOUNT_TYPE_DESTROY` frees the memory for a ref counted type. |
| 59 |
|
| 60 |
**SRS_REFCOUNT_01_008: [** `REFCOUNT_TYPE_DESTROY` shall free the memory allocated by `REFCOUNT_TYPE_CREATE` or `REFCOUNT_TYPE_CREATE_WITH_EXTRA_SIZE`. **]** |
| 61 |
|
| 62 |
**SRS_REFCOUNT_01_009: [** If `counted_type` is NULL, `REFCOUNT_TYPE_DESTROY` shall return. **]** |
| 63 |
|