excit.h 13.3 KB
Newer Older
1 2 3
#ifndef EXCIT_H
#define EXCIT_H 1

4 5
#include <stdlib.h>

Brice Videau's avatar
Brice Videau committed
6 7 8 9
/*
 * The different types of iterator supported. All iterators use the same
 * integer type (ssize_t) for values.
 */
10
enum excit_type_e {
11 12 13 14 15 16 17 18 19
	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 */
20 21
};

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

Brice Videau's avatar
Brice Videau committed
27 28 29
/*
 * The different possible return codes of an excit function.
 */
Brice Videau's avatar
Brice Videau committed
30
enum excit_error_e {
31 32 33 34 35 36 37
	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
38
};
Brice Videau's avatar
Brice Videau committed
39

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

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

Brice Videau's avatar
Brice Videau committed
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
/*******************************************************************************
 * 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
76
struct excit_func_table_s {
Brice Videau's avatar
Brice Videau committed
77 78 79 80 81
	/*
	 * 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
82
	int (*alloc)(excit_t it);
Brice Videau's avatar
Brice Videau committed
83 84 85 86
	/*
	 * 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
87
	void (*free)(excit_t it);
Brice Videau's avatar
Brice Videau committed
88 89 90 91 92
	/*
	 * 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
93
	int (*copy)(excit_t dst_it, const excit_t src_it);
Brice Videau's avatar
Brice Videau committed
94 95 96 97 98
	/*
	 * 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
99
	int (*next)(excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
100 101 102 103 104
	/*
	 * 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
105
	int (*peek)(const excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
106 107 108 109 110
	/*
	 * 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
111
	int (*size)(const excit_t it, ssize_t *size);
Brice Videau's avatar
Brice Videau committed
112 113 114 115 116
	/*
	 * 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
117
	int (*rewind)(excit_t it);
Brice Videau's avatar
Brice Videau committed
118 119 120 121 122
	/*
	 * 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
123
	int (*split)(const excit_t it, ssize_t n, excit_t *results);
Brice Videau's avatar
Brice Videau committed
124 125 126 127 128
	/*
	 * 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
129
	int (*nth)(const excit_t it, ssize_t n, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
130 131 132 133 134
	/*
	 * 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
135
	int (*rank)(const excit_t it, const ssize_t *indexes, ssize_t *n);
Brice Videau's avatar
Brice Videau committed
136 137 138 139 140
	/*
	 * 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
141
	int (*pos)(const excit_t it, ssize_t *n);
Brice Videau's avatar
Brice Videau committed
142 143
};

Brice Videau's avatar
Brice Videau committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
/*
 * 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.
 */
167
excit_t excit_alloc(enum excit_type_e type);
Brice Videau's avatar
Brice Videau committed
168 169 170 171 172 173 174 175 176

/*
 * 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,
177
			 size_t data_size);
Brice Videau's avatar
Brice Videau committed
178 179 180 181 182 183 184

/*
 * 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.
 */
185
excit_t excit_dup(const excit_t it);
Brice Videau's avatar
Brice Videau committed
186 187 188 189 190

/*
 * Frees an iterator and all the iterators it aquired ownership to.
 * "it": iterator to free.
 */
191
void excit_free(excit_t it);
192

Brice Videau's avatar
Brice Videau committed
193 194 195 196 197 198
/*
 * 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.
 */
199
int excit_type(excit_t it, enum excit_type_e *type);
Brice Videau's avatar
Brice Videau committed
200 201 202 203 204 205 206 207

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
208
int excit_dimension(excit_t it, ssize_t *dimension);
209

Brice Videau's avatar
Brice Videau committed
210 211 212 213 214 215 216 217
/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
218
int excit_next(excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
219 220 221 222 223 224 225 226 227

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
228
int excit_peek(const excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
229 230 231 232 233 234

/*
 * Rewinds an iterator to its initial state.
 * "it": an iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
235
int excit_rewind(excit_t it);
Brice Videau's avatar
Brice Videau committed
236 237 238 239 240 241 242

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
243
int excit_size(const excit_t it, ssize_t *size);
Brice Videau's avatar
Brice Videau committed
244 245 246 247 248 249 250 251 252 253

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
254
int excit_split(const excit_t it, ssize_t n, excit_t *results);
255

Brice Videau's avatar
Brice Videau committed
256 257 258
/*
 * Gets the nth element of an iterator.
 * "it": an iterator.
Nicolas Denoyelle's avatar
Nicolas Denoyelle committed
259 260
 * "rank": rank of the element, comprised between 0 and the size of the
 *         iterator.
Brice Videau's avatar
Brice Videau committed
261 262 263 264
 * "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.
 */
Brice Videau's avatar
Brice Videau committed
265
int excit_nth(const excit_t it, ssize_t rank, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
266 267 268 269 270 271 272 273 274

/*
 * 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
275
int excit_rank(const excit_t it, const ssize_t *indexes, ssize_t *rank);
Brice Videau's avatar
Brice Videau committed
276 277 278 279 280 281 282 283 284

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
285
int excit_pos(const excit_t it, ssize_t *rank);
Brice Videau's avatar
Brice Videau committed
286 287 288 289 290 291 292

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

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
303
int excit_cyclic_next(excit_t it, ssize_t *indexes, int *looped);
304

Brice Videau's avatar
Brice Videau committed
305 306 307 308 309 310 311 312
/*
 * 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.
 */
313
int excit_range_init(excit_t it, ssize_t first, ssize_t last, ssize_t step);
314

Brice Videau's avatar
Brice Videau committed
315 316 317 318 319 320 321 322
/*
 * 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.
 */
323
int excit_cons_init(excit_t it, excit_t src, ssize_t n);
324

Brice Videau's avatar
Brice Videau committed
325 326 327 328 329 330 331
/*
 * 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.
 */
332
int excit_repeat_init(excit_t it, excit_t src, ssize_t n);
333

334 335 336 337 338 339 340 341 342 343 344
/*
 * Splits a repeat iterator between repetitions.
 * "it": a product 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 selected iterator is too small to
 * be subdivised in the wanted number or an error code.
 */
int excit_repeat_split(const excit_t it, ssize_t n, excit_t *results);

Brice Videau's avatar
Brice Videau committed
345 346 347 348 349 350
/*
 * 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.
 */
351
int excit_hilbert2d_init(excit_t it, ssize_t order);
352

Brice Videau's avatar
Brice Videau committed
353 354 355 356 357 358
/*
 * 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.
 */
359
int excit_product_add(excit_t it, excit_t added_it);
Brice Videau's avatar
Brice Videau committed
360 361 362 363 364 365 366 367

/*
 * 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.
 */
368
int excit_product_add_copy(excit_t it, excit_t added_it);
Brice Videau's avatar
Brice Videau committed
369 370 371 372 373 374 375

/*
 * 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.
 */
Brice Videau's avatar
Brice Videau committed
376
int excit_product_count(const excit_t it, ssize_t *count);
Brice Videau's avatar
Brice Videau committed
377 378 379 380 381 382 383 384 385 386 387 388

/*
 * 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.
 */
389
int excit_product_split_dim(const excit_t it, ssize_t dim, ssize_t n,
Brice Videau's avatar
Brice Videau committed
390
			    excit_t *results);
391

Brice Videau's avatar
Brice Videau committed
392 393 394 395 396 397 398
/*
 * 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.
 */
399
int excit_slice_init(excit_t it, excit_t src, excit_t indexer);
400
#endif