excit.h 12.8 KB
Newer Older
Brice Videau's avatar
Brice Videau committed
1 2 3
#ifndef EXCIT_H
#define EXCIT_H 1

Brice Videau's avatar
Brice Videau committed
4 5 6 7
/*
 * The different types of iterator supported. All iterators use the same
 * integer type (ssize_t) for values.
 */
Brice Videau's avatar
Brice Videau committed
8
enum excit_type_e {
Brice Videau's avatar
Brice Videau committed
9 10 11 12 13 14 15 16 17
	EXCIT_INVALID, /*!< Tag for invalid iterators */
	EXCIT_RANGE, /*!< Iterator over a range of values */
	EXCIT_CONS, /*!< Sliding window iterator */
	EXCIT_REPEAT, /*!< Ierator that stutters a certain amount of times */
	EXCIT_HILBERT2D, /*!< Hilbert space filing curve */
	EXCIT_PRODUCT, /*!< Iterator over the catesian product of iterators */
	EXCIT_SLICE, /*!< Iterator using another iterator to index a third */
	EXCIT_USER, /*!< User-defined iterator */
	EXCIT_TYPE_MAX /*!< Guard */
Brice Videau's avatar
Brice Videau committed
18 19
};

Brice Videau's avatar
Brice Videau committed
20 21 22
/*
 * Returns the string representation of an iterator type.
 */
23 24
const char * excit_type_name(enum excit_type_e type);

Brice Videau's avatar
Brice Videau committed
25 26 27
/*
 * The different possible return codes of an excit function.
 */
Brice Videau's avatar
Brice Videau committed
28
enum excit_error_e {
Brice Videau's avatar
Brice Videau committed
29 30 31 32 33 34 35
	EXCIT_SUCCESS, /*!< Sucess */
	EXCIT_STOPIT, /*!< Iteration space is depleted */
	EXCIT_ENOMEM, /*!< Out of memory */
	EXCIT_EINVAL, /*!< Parameter has an invalid value */
	EXCIT_EDOM, /*!< Parameter is out of possible domain */
	EXCIT_ENOTSUP, /*!< Operation is not supported */
	EXCIT_ERROR_MAX /*!< Guard */
Brice Videau's avatar
Brice Videau committed
36
};
Brice Videau's avatar
Brice Videau committed
37

Brice Videau's avatar
Brice Videau committed
38 39 40
/*
 * Returns the string representation of a return code.
 */
41 42
const char * excit_error_name(enum excit_error_e err);

Brice Videau's avatar
Brice Videau committed
43 44 45
/*
 * Opaque structure of an iterator
 */
Brice Videau's avatar
Brice Videau committed
46 47
typedef struct excit_s *excit_t;

Brice Videau's avatar
Brice Videau committed
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
/*******************************************************************************
 * Programming interface for user-defined iterators:
 ******************************************************************************/

/*
 * Sets the dimension of a user-defined iterator.
 * "it": a user-defined iterator.
 * "dimension": the new dimension of the iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_set_dimension(excit_t it, ssize_t dimension);

/*
 * Gets the inner data pointer of a user-defined iterator.
 * "it": a user-defined iterator.
 * "data": a pointer to a pointer variable where the result will be written.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_get_data(excit_t it, void **data);

/*
 * Function table used by iterators. A user-defined iterator must provide it's
 * own table, if some of the functions are defined NULL, the corresponding
 * functionalities will be considered unsupported and the broker will return
 * -EXCIT_ENOTSUP.
 */
Brice Videau's avatar
Brice Videau committed
74
struct excit_func_table_s {
Brice Videau's avatar
Brice Videau committed
75 76 77 78 79
	/*
	 * This function is called during excit_alloc, after the memory
	 * allocation, the inner data pointer will already be set.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
80
	int (*alloc)(excit_t it);
Brice Videau's avatar
Brice Videau committed
81 82 83 84
	/*
	 * This function is called during excit_free. After this function is
	 * called the iterator and the data will be freed.
	 */
Brice Videau's avatar
Brice Videau committed
85
	void (*free)(excit_t it);
Brice Videau's avatar
Brice Videau committed
86 87 88 89 90
	/*
	 * This funciton is called during excit_dup. It is responsible for
	 * duplicating the content of the inner data between src_it and dst_it.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
91
	int (*copy)(excit_t dst_it, const excit_t src_it);
Brice Videau's avatar
Brice Videau committed
92 93 94 95 96
	/*
	 * This function is responsible for implementing the next functionality
	 * of the iterator.
	 * Returns EXCIT_SUCCESS, EXCIT_STOPIT or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
97
	int (*next)(excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
98 99 100 101 102
	/*
	 * This function is responsible for implementing the peek functionality
	 * of the iterator.
	 * Returns EXCIT_SUCCESS, EXCIT_STOPIT or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
103
	int (*peek)(const excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
104 105 106 107 108
	/*
	 * This function is responsible for implementing the size functionality
	 * of the iterator.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
109
	int (*size)(const excit_t it, ssize_t *size);
Brice Videau's avatar
Brice Videau committed
110 111 112 113 114
	/*
	 * This function is responsible for implementing the rewind
	 * functionality of the iterator.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
115
	int (*rewind)(excit_t it);
Brice Videau's avatar
Brice Videau committed
116 117 118 119 120
	/*
	 * This function is responsible for implementing the split
	 * functionality of the iterator.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
121
	int (*split)(const excit_t it, ssize_t n, excit_t *results);
Brice Videau's avatar
Brice Videau committed
122 123 124 125 126
	/*
	 * This function is responsible for implementing the nth functionality
	 * of the iterator.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
127
	int (*nth)(const excit_t it, ssize_t n, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
128 129 130 131 132
	/*
	 * This function is responsible for implementing the rank functionality
	 * of the iterator.
	 * Returns EXCIT_SUCCESS or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
133
	int (*rank)(const excit_t it, const ssize_t *indexes, ssize_t *n);
Brice Videau's avatar
Brice Videau committed
134 135 136 137 138
	/*
	 * This function is responsible for implementing the pos functionality
	 * of the iterator.
	 * Returns EXCIT_SUCCESS, EXCIT_STOPIT or an error code.
	 */
Brice Videau's avatar
Brice Videau committed
139 140 141
	int (*pos)(const excit_t it, ssize_t *n);
};

Brice Videau's avatar
Brice Videau committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
/*
 * Sets the function table of an iterator.
 * "it": an iterator.
 * "func_table": a pointer to the new function table.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_set_func_table(excit_t it, struct excit_func_table_s *func_table);

/*
 * Gets a pointer to the function table of an iterator.
 * "it": an iterator.
 * "func_table": a pointer to a pointer variable where the result will be
 *               written.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_get_func_table(excit_t it, struct excit_func_table_s **func_table);

/*
 * Allocates a new iterator of the given type.
 * "type": the type of the iterator, cannot be EXCIT_USER.
 * Returns an iterator that will need to be freed unless ownership is
 * transfered or NULL if an error occured.
 */
Brice Videau's avatar
Brice Videau committed
165
excit_t excit_alloc(enum excit_type_e type);
Brice Videau's avatar
Brice Videau committed
166 167 168 169 170 171 172 173 174

/*
 * Allocates a user-defined iterator.
 * "func_table": the table of function excit will use.
 * "data_size": the size of the inner data to allocate.
 * Returns an iterator that will need to be freed unless ownership is
 * transfered or NULL if an error occured.
 */
excit_t excit_alloc_user(struct excit_func_table_s *func_table,
175
			 size_t data_size);
Brice Videau's avatar
Brice Videau committed
176 177 178 179 180 181 182

/*
 * Duplicates an iterator.
 * "it": iterator to duplicate.
 * Returns an iterator that will need to be freed unless ownership is
 * transfered or NULL if an error occured.
 */
183
excit_t excit_dup(const excit_t it);
Brice Videau's avatar
Brice Videau committed
184 185 186 187 188

/*
 * Frees an iterator and all the iterators it aquired ownership to.
 * "it": iterator to free.
 */
189
void excit_free(excit_t it);
Brice Videau's avatar
Brice Videau committed
190

Brice Videau's avatar
Brice Videau committed
191 192 193 194 195 196
/*
 * Get the type of an iterator
 * "it": an iterator.
 * "type": a pointer where the result will be written.
 * Returns EXCIT_SUCCESS or an error code.
 */
197
int excit_type(excit_t it, enum excit_type_e *type);
Brice Videau's avatar
Brice Videau committed
198 199 200 201 202 203 204 205

/*
 * Get the dimension of an iterator. This is the number of elements of the array
 * of ssize_t that is expected by the peek, next, nth and n functionalities.
 * "it": an iterator.
 * "dimension": a pointer where the result will be written.
 * Returns EXCIT_SUCCESS or an error code.
 */
206
int excit_dimension(excit_t it, ssize_t *dimension);
Brice Videau's avatar
Brice Videau committed
207

Brice Videau's avatar
Brice Videau committed
208 209 210 211 212 213 214 215
/*
 * Gets the current element of an iterator and increments it.
 * "it": an iterator.
 * "indexes": an array of indexes with a dimension corresponding to that of the
 *            iterator, no results is returned if NULL.
 * Returns EXCIT_SUCCESS if a valid element was retured or EXCIT_STOPIT if the
 * iterator is depleted or an error code.
 */
216
int excit_next(excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
217 218 219 220 221 222 223 224 225

/*
 * Gets the current element of an iterator.
 * "it": an iterator.
 * "indexes": an array of indexes with a dimension corresponding to that of the
 *            iterator, no results is returned if NULL.
 * Returns EXCIT_SUCCESS if a valid element was retured or EXCIT_STOPIT if the
 * iterator is depleted or an error code.
 */
226
int excit_peek(const excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
227 228 229 230 231 232

/*
 * Rewinds an iterator to its initial state.
 * "it": an iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
233
int excit_rewind(excit_t it);
Brice Videau's avatar
Brice Videau committed
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

/*
 * Gets the number of elements of an iterator.
 * "it": an iterator.
 * "size": an pointer to the variable where the result will be stored.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_size(const excit_t it, ssize_t *size);

/*
 * Splits an iterator envenly into several suub iterators.
 * "it": an iterator.
 * "n": number of iterators desired.
 * "results": an array of at least n excit_t, or NULL in which case no iterator
 *            is created.
 * Returns EXCIT_SUCCESS, -EXCIT_EDOM if the source iterator is too small to be
 * subdivised in the wanted number or an error code.
 */
252
int excit_split(const excit_t it, ssize_t n, excit_t *results);
Brice Videau's avatar
Brice Videau committed
253

Brice Videau's avatar
Brice Videau committed
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
/*
 * Gets the nth element of an iterator.
 * "it": an iterator.
 * "rank": rank of the element, comprised between 0 and the size of the iterator.
 * "indexes": an array of indexes with a dimension corresponding to that of the
 *            iterator, no results is returned if NULL.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_nth(const excit_t it, ssize_t rank, ssize_t *indexes);

/*
 * Gets the rank of an element of an iterator.
 * "it": an iterator.
 * "indexes": an array of indexes corresponding to the element of the iterator.
 * "rank": a pointer to a variable where the result will be stored, no result is
 *         returned if NULL.
 * Returns EXCIT_SUCCESS or an error code.
 */
Brice Videau's avatar
Brice Videau committed
272
int excit_rank(const excit_t it, const ssize_t *indexes, ssize_t *rank);
Brice Videau's avatar
Brice Videau committed
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289

/*
 * Gets the position of the iterator.
 * "it": an iterator.
 * "rank": a pointer to a variable where the rank of the current element will be
 *         stored, no result is returned if NULL.
 * Returns EXCIT_SUCCESS or EXCIT_STOPIT if the iterator is depleted or an error
 * code.
 */
int excit_pos(const excit_t it, ssize_t *rank);

/*
 * Increments the iterator.
 * "it": an iterator.
 * Returns EXCIT_SUCCESS or EXCIT_STOPIT if the iterator is depleted or an error
 * code.
 */
290
int excit_skip(excit_t it);
Brice Videau's avatar
Brice Videau committed
291 292 293 294 295 296 297 298 299

/*
 * Gets the current element of an iterator, rewinding it first if the iterator
 * was depleted. The iterator is incremented.
 * "it": an iterator.
 * "indexes": an array of indexes with a dimension corresponding to that of the
 *            iterator, no results is returned if NULL.
 * Returns EXCIT_SUCCESS or an error code.
 */
300
int excit_cyclic_next(excit_t it, ssize_t *indexes, int *looped);
Brice Videau's avatar
Brice Videau committed
301

Brice Videau's avatar
Brice Videau committed
302 303 304 305 306 307 308 309
/*
 * Initializes a range iterator to iterate from first to last (included) by sep.
 * "it": a range iterator.
 * "first": first value of the range.
 * "last": last value of the range.
 * "step": between elements of the range. Must be non null, can be negative.
 * Returns EXCIT_SUCCESS or an error code.
 */
310
int excit_range_init(excit_t it, ssize_t first, ssize_t last, ssize_t step);
Brice Videau's avatar
Brice Videau committed
311

Brice Videau's avatar
Brice Videau committed
312 313 314 315 316 317 318 319
/*
 * Initializes a sliding window iterator over another iterator.
 * "it": a cons iterator.
 * "src": the original iterator. Ownership is transfered.
 * "n": size of the window, must not be superior to the size of the src
 *      iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
320
int excit_cons_init(excit_t it, excit_t src, ssize_t n);
Brice Videau's avatar
Brice Videau committed
321

Brice Videau's avatar
Brice Videau committed
322 323 324 325 326 327 328
/*
 * Initializes a repeat iterator over another iterator.
 * "it": a repeat iterator.
 * "src": the original iterator. Ownership is transfered.
 * "n": number of repeat of each element of the src iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
329
int excit_repeat_init(excit_t it, excit_t src, ssize_t n);
Brice Videau's avatar
Brice Videau committed
330

Brice Videau's avatar
Brice Videau committed
331 332 333 334 335 336
/*
 * Creates a two dimensional Hilbert space-filling curve iterator.
 * "it": an hilbert2d iterator.
 * "order": the iteration space is (2^order - 1)^2.
 * Returns EXCIT_SUCCESS or an error code.
 */
337
int excit_hilbert2d_init(excit_t it, ssize_t order);
Brice Videau's avatar
Brice Videau committed
338

Brice Videau's avatar
Brice Videau committed
339 340 341 342 343 344
/*
 * Adds another iterator to a product iterator.
 * "it": a repeat iterator.
 * "added_it": the added iterator. Ownership is transfered.
 * Returns EXCIT_SUCCESS or an error code.
 */
345
int excit_product_add(excit_t it, excit_t added_it);
Brice Videau's avatar
Brice Videau committed
346 347 348 349 350 351 352 353

/*
 * Adds another iterator to a product iterator without transfering ownership.
 * "it": a product iterator.
 * "added_it": the added iterator. Ownership is not transfered, a duplicate is
 *             created instead.
 * Returns EXCIT_SUCCESS or an error code.
 */
354
int excit_product_add_copy(excit_t it, excit_t added_it);
Brice Videau's avatar
Brice Videau committed
355 356 357 358 359 360 361

/*
 * Gets the number of iterator inside a product iterator.
 * "it": a product iterator.
 * "count": a pointer to a variable where the result will be stored.
 * Returns EXCIT_SUCCESS or an error code.
 */
362
int excit_product_count(const excit_t it, ssize_t *count);
Brice Videau's avatar
Brice Videau committed
363 364 365 366 367 368 369 370 371 372 373 374

/*
 * Splits a product iterator along the nth iterator.
 * "it": a product iterator.
 * "dim": the number of the iterator to split, must be comprised between 0 and
 *        the number of iterator inside the product iterator - 1.
 * "n": number of iterators desired.
 * "results": an array of at least n excit_t, or NULL in which case no iterator
 *            is created.
 * Returns EXCIT_SUCCESS, -EXCIT_EDOM if the selected iterator is too small to
 * be subdivised in the wanted number or an error code.
 */
375 376
int excit_product_split_dim(const excit_t it, ssize_t dim, ssize_t n,
			    excit_t *results);
Brice Videau's avatar
Brice Videau committed
377

Brice Videau's avatar
Brice Videau committed
378 379 380 381 382 383 384
/*
 * Initializes a slice iterator by giving asrc iterator and an indexer iterator.
 * "it": a slice iterator.
 * "src": the iterator whom elements are to be returned.
 * "indexer": the iterator that will provide the rank of the elements to return.
 * Returns EXCIT_SUCCESS or an error code.
 */
385
int excit_slice_init(excit_t it, excit_t src, excit_t indexer);
Brice Videau's avatar
Brice Videau committed
386
#endif