excit.h 13.8 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 20
  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_TLEAF, /*!< Iterator on leaves of a balanced tree */
  EXCIT_USER, /*!< User-defined iterator */
  EXCIT_TYPE_MAX /*!< Guard */
21 22
};

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

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

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

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

Brice Videau's avatar
Brice Videau committed
51 52 53 54 55
/*******************************************************************************
 * Programming interface for user-defined iterators:
 ******************************************************************************/

/*
56 57
 * Sets the dimension of a (user-defined) iterator.
 * "it": a (user-defined) iterator.
Brice Videau's avatar
Brice Videau committed
58 59 60 61 62 63
 * "dimension": the new dimension of the iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
int excit_set_dimension(excit_t it, ssize_t dimension);

/*
64 65 66 67 68 69 70 71 72
 * Gets the dimension of an iterator.
 * "it": the iterator.
 * Returns the dimension or -1 if it is NULL.
 */
ssize_t excit_get_dimension(excit_t it);
  
/*
 * Gets the inner data pointer of a (user-defined) iterator.
 * "it": a (user-defined) iterator.
Brice Videau's avatar
Brice Videau committed
73 74 75 76 77 78 79 80 81 82 83
 * "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
84
struct excit_func_table_s {
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
  /*
   * 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.
   */
  int (*alloc)(excit_t it);
  /*
   * This function is called during excit_free. After this function is
   * called the iterator and the data will be freed.
   */
  void (*free)(excit_t it);
  /*
   * 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.
   */
  int (*copy)(excit_t dst_it, const excit_t src_it);
  /*
   * This function is responsible for implementing the next functionality
   * of the iterator.
   * Returns EXCIT_SUCCESS, EXCIT_STOPIT or an error code.
   */
  int (*next)(excit_t it, ssize_t *indexes);
  /*
   * This function is responsible for implementing the peek functionality
   * of the iterator.
   * Returns EXCIT_SUCCESS, EXCIT_STOPIT or an error code.
   */
  int (*peek)(const excit_t it, ssize_t *indexes);
  /*
   * This function is responsible for implementing the size functionality
   * of the iterator.
   * Returns EXCIT_SUCCESS or an error code.
   */
  int (*size)(const excit_t it, ssize_t *size);
  /*
   * This function is responsible for implementing the rewind
   * functionality of the iterator.
   * Returns EXCIT_SUCCESS or an error code.
   */
  int (*rewind)(excit_t it);
  /*
   * This function is responsible for implementing the split
   * functionality of the iterator.
   * Returns EXCIT_SUCCESS or an error code.
   */
  int (*split)(const excit_t it, ssize_t n, excit_t *results);
  /*
   * This function is responsible for implementing the nth functionality
   * of the iterator.
   * Returns EXCIT_SUCCESS or an error code.
   */
  int (*nth)(const excit_t it, ssize_t n, ssize_t *indexes);
  /*
   * This function is responsible for implementing the rank functionality
   * of the iterator.
   * Returns EXCIT_SUCCESS or an error code.
   */
  int (*rank)(const excit_t it, const ssize_t *indexes, ssize_t *n);
  /*
   * This function is responsible for implementing the pos functionality
   * of the iterator.
   * Returns EXCIT_SUCCESS, EXCIT_STOPIT or an error code.
   */
  int (*pos)(const excit_t it, ssize_t *n);
Brice Videau's avatar
Brice Videau committed
150 151
};

Brice Videau's avatar
Brice Videau committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
/*
 * 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.
 */
175
excit_t excit_alloc(enum excit_type_e type);
Brice Videau's avatar
Brice Videau committed
176 177 178 179 180 181 182 183 184

/*
 * 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,
185
			 size_t data_size);
Brice Videau's avatar
Brice Videau committed
186 187 188 189 190 191 192

/*
 * 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.
 */
193
excit_t excit_dup(const excit_t it);
Brice Videau's avatar
Brice Videau committed
194 195 196 197 198

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

Brice Videau's avatar
Brice Videau committed
201 202 203 204 205 206
/*
 * 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.
 */
207
int excit_type(excit_t it, enum excit_type_e *type);
Brice Videau's avatar
Brice Videau committed
208 209 210 211 212 213 214 215

/*
 * 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.
 */
216
int excit_dimension(excit_t it, ssize_t *dimension);
217

Brice Videau's avatar
Brice Videau committed
218 219 220 221 222 223 224 225
/*
 * 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.
 */
226
int excit_next(excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
227 228 229 230 231 232 233 234 235

/*
 * 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.
 */
236
int excit_peek(const excit_t it, ssize_t *indexes);
Brice Videau's avatar
Brice Videau committed
237 238 239 240 241 242

/*
 * Rewinds an iterator to its initial state.
 * "it": an iterator.
 * Returns EXCIT_SUCCESS or an error code.
 */
243
int excit_rewind(excit_t it);
Brice Videau's avatar
Brice Videau committed
244 245 246 247 248 249 250 251 252 253 254 255 256 257

/*
 * 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
258
 / *            is created.
Brice Videau's avatar
Brice Videau committed
259 260 261
 * Returns EXCIT_SUCCESS, -EXCIT_EDOM if the source iterator is too small to be
 * subdivised in the wanted number or an error code.
 */
262
int excit_split(const excit_t it, ssize_t n, excit_t *results);
263

Brice Videau's avatar
Brice Videau committed
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
/*
 * 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.
 */
282
int excit_rank(const excit_t it, const ssize_t *indexes, ssize_t *rank);
Brice Videau's avatar
Brice Videau committed
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299

/*
 * 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.
 */
300
int excit_skip(excit_t it);
Brice Videau's avatar
Brice Videau committed
301 302 303 304 305 306 307 308 309

/*
 * 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.
 */
310
int excit_cyclic_next(excit_t it, ssize_t *indexes, int *looped);
311

Brice Videau's avatar
Brice Videau committed
312 313 314 315 316 317 318 319
/*
 * 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.
 */
320
int excit_range_init(excit_t it, ssize_t first, ssize_t last, ssize_t step);
321

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

Brice Videau's avatar
Brice Videau committed
332 333 334 335 336 337 338
/*
 * 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.
 */
339
int excit_repeat_init(excit_t it, excit_t src, ssize_t n);
340

Brice Videau's avatar
Brice Videau committed
341 342 343 344 345 346
/*
 * 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.
 */
347
int excit_hilbert2d_init(excit_t it, ssize_t order);
348

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

/*
 * 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.
 */
364
int excit_product_add_copy(excit_t it, excit_t added_it);
Brice Videau's avatar
Brice Videau committed
365 366 367 368 369 370 371

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

/*
 * 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.
 */
385 386
int excit_product_split_dim(const excit_t it, ssize_t dim, ssize_t n,
			    excit_t *results);
387

Brice Videau's avatar
Brice Videau committed
388 389 390 391 392 393 394
/*
 * 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.
 */
395
int excit_slice_init(excit_t it, excit_t src, excit_t indexer);
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412


enum tleaf_it_policy_e {
  ROUND_ROBIN, /* Iterate on tree leaves in a round-robin fashion */
  SCATTER /* Iterate on tree leaves such spreading as much as possible */
};


/*
 * Initialize a tleaf iterator by giving its depth, levels arity and iteration policy.
 * "it": a tleaf iterator
 * "depth": the total number of levels of the tree, including leaves
 * "arity": For each level, the number of children attached to a node. Leaves have no children, hence last level arity must be 0.
 * "iter_policy": A policy for iteration on leaves.
 */
int excit_tleaf_init(excit_t it, const ssize_t depth, const ssize_t* arity, const enum tleaf_it_policy_e iter_policy);

413
#endif