1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
/*
REF ARRAY
Header file for of the dynamic array with reference count.
Copyright (C) Dmitri Pal <dpal@redhat.com> 2009
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef REF_ARRAY_H
#define REF_ARRAY_H
#include <stdint.h>
#include <stdlib.h>
struct ref_array;
#ifndef EOK
#define EOK 0
#endif
/** @mainpage The Referenced Array Interface
*
* The referenced array interface is a dynamically allocated
* array of data of any type. The array can be shared by
* multiple objects to avoid data duplication.
*
* The array is created once and then any number of
* the references can be requested. The references are pointers
* to the array. Each reference must be freed after use.
* Freeing last reference to the array would free the array's storage.
*
* The array does not have any knowledge of the data type
* of the actual data stored in the array. All elements of the array
* are of the same size as prescribed by caller when the array is created.
* The caller can potentially mix different types of data in the array
* but this should be done with caution.
*
* At the moment the interface is not complete.
* It provides basic functionality required to support other
* components. In future it might make sense to add entry points
* to insert and delete elements from the array.
* Current use cases do not require this kind of
* functionality so it is left out of the implementation.
*
*/
/**
* @defgroup ref_array Interface
* @{
*/
/**
* @brief Enumeration of the delete modes
*
* When the array is destroyed each element of the array
* most likely needs to be freed. Same is true when an element
* is removed from the array. However the caller might need
* to do different things with the data depending on whether
* the array is destroyed or whether the element is removed.
* This enumeration defines constants that you used to indicate
* which operation was performed.
*/
typedef enum
{
REF_ARRAY_DESTROY,
REF_ARRAY_DELETE,
} ref_array_del_enum;
/**
* @brief Element cleanup callback
*
* Callback that can be provided by a caller
* to free data when the storage is actually destroyed.
*/
typedef void (*ref_array_fn)(void *elem,
ref_array_del_enum type,
void *data);
/**
* @brief Create referenced array
*
* @param[out] ra Newly created array object.
* @param[in] elem Element size in bytes.
* @param[in] grow_by Defines how many elements
* should be allocated together
* as one chunk.
* @param[in] cb Cleanup callback.
* @param[in] data Caller supplied data
* passed to cleanup callback.
*
* @return 0 - Success.
* @return ENOMEM - No memory.
* @return EINVAL - Invalid argument.
*/
int ref_array_create(struct ref_array **ra,
size_t elem,
uint32_t grow_by,
ref_array_fn cb,
void *data);
/**
* @brief Get new reference to an array
*
* @param[in] ra Existing array object.
*
* @return A new reference to an array object.
* @return NULL - Invalid argument.
*/
struct ref_array *ref_array_getref(struct ref_array *ra);
/**
* @brief Delete the array
*
* @param[in] ra Existing array object
* or a reference.
*
*/
void ref_array_destroy(struct ref_array *ra);
/**
* @brief Add new element to the array
*
* Appends an element to the end of the array.
*
* @param[in] ra Existing array object.
* @param[in] element Pointer to data.
* The number of bytes
* defined at the array creation
* as the array size will be copied
* into the array element.
*
* @return 0 - Success.
* @return ENOMEM - No memory.
* @return EINVAL - Invalid argument.
*/
int ref_array_append(struct ref_array *ra, void *element);
/**
* @brief Get element data
*
* Retrieves data from the array element.
*
* @param[in] ra Existing array object.
* @param[in] idx Index of the array element.
* @param[in] acptr Pointer to the memory
* where the element's data
* will be copied. Can be NULL.
* In this case nothing is copied.
*
* @return Pointer to the data stored in the element.
* Conventionally it should be a const pointer,
* however such declaration would make using
* variable that receives the result of this
* function immutable. This is very inconvenient
* because such variable should be able to
* point to data related to multiple elements
* of the array.
*
* @return Pointer to the element's data.
* @return NULL if index is out of range.
*/
void *ref_array_get(struct ref_array *ra, uint32_t idx, void *acptr);
/**
* @brief Get array length
*
* Determines length of the array.
*
* @param[in] ra Existing array object.
* @param[out] len Variable will receive
* the length of the array.
*
* @return 0 - Success.
* @return EINVAL - Invalid argument.
*/
int ref_array_getlen(struct ref_array *ra, uint32_t *len);
/**
* @brief Array length
*
* Alternative function to get length.
*
* @param[in] ra Existing array object.
*
* @return Length of the array. Returns 0 if the array is invalid.
*/
uint32_t ref_array_len(struct ref_array *ra);
/**
* @}
*/
#endif
|
