Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/refcount_requirements.md

raw
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