src/simclist.h

   1 /*
   2  * Copyright (c) 2007,2008 Mij <mij@bitchx.it>
   3  *
   4  * Permission to use, copy, modify, and distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17
  18 /*
  19  * SimCList library. See http://mij.oltrelinux.com/devel/simclist
  20  */
  21
  22
  23 #ifndef SIMCLIST_H
  24 #define SIMCLIST_H
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #include <inttypes.h>
  31 #include <errno.h>
  32 #include <sys/types.h>
  33
  34 #ifndef SIMCLIST_NO_DUMPRESTORE
  35 #   ifndef _WIN32
  36 #       include <sys/time.h>    /* list_dump_info_t's struct timeval */
  37 #   else
  38 #       include <time.h>
  39 #   endif
  40 #endif
  41
  42
  43 /* Be friend of both C90 and C99 compilers */
  44 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
  45     /* "inline" and "restrict" are keywords */
  46 #else
  47 #   define inline           /* inline */
  48 #   define restrict         /* restrict */
  49 #endif
  50
  51
  52 /**
  53  * Type representing list hashes.
  54  *
  55  * This is a signed integer value.
  56  */
  57 typedef int32_t list_hash_t;
  58
  59 #ifndef SIMCLIST_NO_DUMPRESTORE
  60 typedef struct {
  61     uint16_t version;           /* dump version */
  62     struct timeval timestamp;   /* when the list has been dumped, seconds since UNIX epoch */
  63     uint32_t list_size;
  64     uint32_t list_numels;
  65     list_hash_t list_hash;      /* hash of the list when dumped, or 0 if invalid */
  66     uint32_t dumpsize;
  67     int consistent;             /* 1 if the dump is verified complete/consistent; 0 otherwise */
  68 } list_dump_info_t;
  69 #endif
  70
  71 /**
  72  * a comparator of elements.
  73  *
  74  * A comparator of elements is a function that:
  75  *      -# receives two references to elements a and b
  76  *      -# returns {<0, 0, >0} if (a > b), (a == b), (a < b) respectively
  77  *
  78  * It is responsability of the function to handle possible NULL values.
  79  */
  80 typedef int (*element_comparator)(const void *a, const void *b);
  81
  82 /**
  83  * a seeker of elements.
  84  *
  85  * An element seeker is a function that:
  86  *      -# receives a reference to an element el
  87  *      -# receives a reference to some indicator data
  88  *      -# returns non-0 if the element matches the indicator, 0 otherwise
  89  *
  90  * It is responsability of the function to handle possible NULL values in any
  91  * argument.
  92  */
  93 typedef int (*element_seeker)(const void *el, const void *indicator);
  94
  95 /**
  96  * an element lenght meter.
  97  *
  98  * An element meter is a function that:
  99  *      -# receives the reference to an element el
 100  *      -# returns its size in bytes
 101  *
 102  * It is responsability of the function to handle possible NULL values.
 103  */
 104 typedef size_t (*element_meter)(const void *el);
 105
 106 /**
 107  * a function computing the hash of elements.
 108  *
 109  * An hash computing function is a function that:
 110  *      -# receives the reference to an element el
 111  *      -# returns a hash value for el
 112  *
 113  * It is responsability of the function to handle possible NULL values.
 114  */
 115 typedef list_hash_t (*element_hash_computer)(const void *el);
 116
 117 /**
 118  * a function for serializing an element.
 119  *
 120  * A serializer function is one that gets a reference to an element,
 121  * and returns a reference to a buffer that contains its serialization
 122  * along with the length of this buffer.
 123  * It is responsability of the function to handle possible NULL values,
 124  * returning a NULL buffer and a 0 buffer length.
 125  *
 126  * These functions have 3 goals:
 127  *  -# "freeze" and "flatten" the memory representation of the element
 128  *  -# provide a portable (wrt byte order, or type size) representation of the element, if the dump can be used on different sw/hw combinations
 129  *  -# possibly extract a compressed representation of the element
 130  *
 131  * @param el                reference to the element data
 132  * @param serialize_buffer  reference to fill with the length of the buffer
 133  * @return                  reference to the buffer with the serialized data
 134  */
 135 typedef void *(*element_serializer)(const void *restrict el, uint32_t *restrict serializ_len);
 136
 137 /**
 138  * a function for un-serializing an element.
 139  *
 140  * An unserializer function accomplishes the inverse operation of the
 141  * serializer function.  An unserializer function is one that gets a
 142  * serialized representation of an element and turns it backe to the original
 143  * element. The serialized representation is passed as a reference to a buffer
 144  * with its data, and the function allocates and returns the buffer containing
 145  * the original element, and it sets the length of this buffer into the
 146  * integer passed by reference.
 147  *
 148  * @param data              reference to the buffer with the serialized representation of the element
 149  * @param data_len          reference to the location where to store the length of the data in the buffer returned
 150  * @return                  reference to a buffer with the original, unserialized representation of the element
 151  */
 152 typedef void *(*element_unserializer)(const void *restrict data, uint32_t *restrict data_len);
 153
 154 /* [private-use] list entry -- olds actual user datum */
 155 struct list_entry_s {
 156     void *data;
 157
 158     /* doubly-linked list service references */
 159     struct list_entry_s *next;
 160     struct list_entry_s *prev;
 161 };
 162
 163 /* [private-use] list attributes */
 164 struct list_attributes_s {
 165     /* user-set routine for comparing list elements */
 166     element_comparator comparator;
 167     /* user-set routing for seeking elements */
 168     element_seeker seeker;
 169     /* user-set routine for determining the length of an element */
 170     element_meter meter;
 171     int copy_data;
 172     /* user-set routine for computing the hash of an element */
 173     element_hash_computer hasher;
 174     /* user-set routine for serializing an element */
 175     element_serializer serializer;
 176     /* user-set routine for unserializing an element */
 177     element_unserializer unserializer;
 178 };
 179
 180 /** list object */
 181 typedef struct {
 182     struct list_entry_s *head_sentinel;
 183     struct list_entry_s *tail_sentinel;
 184     struct list_entry_s *mid;
 185
 186     unsigned int numels;
 187
 188     /* array of spare elements */
 189     struct list_entry_s **spareels;
 190     unsigned int spareelsnum;
 191
 192 #ifdef SIMCLIST_WITH_THREADS
 193     /* how many threads are currently running */
 194     unsigned int threadcount;
 195 #endif
 196
 197     /* service variables for list iteration */
 198     int iter_active;
 199     unsigned int iter_pos;
 200     struct list_entry_s *iter_curentry;
 201
 202     /* list attributes */
 203     struct list_attributes_s attrs;
 204 } list_t;
 205
 206 /**
 207  * initialize a list object for use.
 208  *
 209  * @param l     must point to a user-provided memory location
 210  * @return      0 for success. -1 for failure
 211  */
 212 int list_init(list_t *restrict l);
 213
 214 /**
 215  * completely remove the list from memory.
 216  *
 217  * This function is the inverse of list_init(). It is meant to be called when
 218  * the list is no longer going to be used. Elements and possible memory taken
 219  * for internal use are freed.
 220  *
 221  * @param l     list to destroy
 222  */
 223 void list_destroy(list_t *restrict l);
 224
 225 /**
 226  * set the comparator function for list elements.
 227  *
 228  * Comparator functions are used for searching and sorting. If NULL is passed
 229  * as reference to the function, the comparator is disabled.
 230  *
 231  * @param l     list to operate
 232  * @param comparator_fun    pointer to the actual comparator function
 233  * @return      0 if the attribute was successfully set; -1 otherwise
 234  *
 235  * @see element_comparator()
 236  */
 237 int list_attributes_comparator(list_t *restrict l, element_comparator comparator_fun);
 238
 239 /**
 240  * set a seeker function for list elements.
 241  *
 242  * Seeker functions are used for finding elements. If NULL is passed as reference
 243  * to the function, the seeker is disabled.
 244  *
 245  * @param l     list to operate
 246  * @param seeker_fun    pointer to the actual seeker function
 247  * @return      0 if the attribute was successfully set; -1 otherwise
 248  *
 249  * @see element_seeker()
 250  */
 251 int list_attributes_seeker(list_t *restrict l, element_seeker seeker_fun);
 252
 253 /**
 254  * require to free element data when list entry is removed (default: don't free).
 255  *
 256  * [ advanced preference ]
 257  *
 258  * By default, when an element is removed from the list, it disappears from
 259  * the list by its actual data is not free()d. With this option, every
 260  * deletion causes element data to be freed.
 261  *
 262  * It is responsability of this function to correctly handle NULL values, if
 263  * NULL elements are inserted into the list.
 264  *
 265  * @param l             list to operate
 266  * @param metric_fun    pointer to the actual metric function
 267  * @param copy_data     0: do not free element data (default); non-0: do free
 268  * @return          0 if the attribute was successfully set; -1 otherwise
 269  *
 270  * @see element_meter()
 271  * @see list_meter_int8_t()
 272  * @see list_meter_int16_t()
 273  * @see list_meter_int32_t()
 274  * @see list_meter_int64_t()
 275  * @see list_meter_uint8_t()
 276  * @see list_meter_uint16_t()
 277  * @see list_meter_uint32_t()
 278  * @see list_meter_uint64_t()
 279  * @see list_meter_float()
 280  * @see list_meter_double()
 281  * @see list_meter_string()
 282  */
 283 int list_attributes_copy(list_t *restrict l, element_meter metric_fun, int copy_data);
 284
 285 /**
 286  * set the element hash computing function for the list elements.
 287  *
 288  * [ advanced preference ]
 289  *
 290  * An hash can be requested depicting the list status at a given time. An hash
 291  * only depends on the elements and their order. By default, the hash of an
 292  * element is only computed on its reference. With this function, the user can
 293  * set a custom function computing the hash of an element. If such function is
 294  * provided, the list_hash() function automatically computes the list hash using
 295  * the custom function instead of simply referring to element references.
 296  *
 297  * @param l             list to operate
 298  * @param hash_computer_fun pointer to the actual hash computing function
 299  * @return              0 if the attribute was successfully set; -1 otherwise
 300  *
 301  * @see element_hash_computer()
 302  */
 303 int list_attributes_hash_computer(list_t *restrict l, element_hash_computer hash_computer_fun);
 304
 305 /**
 306  * set the element serializer function for the list elements.
 307  *
 308  * [ advanced preference ]
 309  *
 310  * Serialize functions are used for dumping the list to some persistent
 311  * storage.  The serializer function is called for each element; it is passed
 312  * a reference to the element and a reference to a size_t object. It will
 313  * provide (and return) the buffer with the serialization of the element and
 314  * fill the size_t object with the length of this serialization data.
 315  *
 316  * @param   l   list to operate
 317  * @param   serializer_fun  pointer to the actual serializer function
 318  * @return      0 if the attribute was successfully set; -1 otherwise
 319  *
 320  * @see     element_serializer()
 321  * @see     list_dump_filedescriptor()
 322  * @see     list_restore_filedescriptor()
 323  */
 324 int list_attributes_serializer(list_t *restrict l, element_serializer serializer_fun);
 325
 326 /**
 327  * set the element unserializer function for the list elements.
 328  *
 329  * [ advanced preference ]
 330  *
 331  * Unserialize functions are used for restoring the list from some persistent
 332  * storage. The unserializer function is called for each element segment read
 333  * from the storage; it is passed the segment and a reference to an integer.
 334  * It shall allocate and return a buffer compiled with the resumed memory
 335  * representation of the element, and set the integer value to the length of
 336  * this buffer.
 337  *
 338  * @param   l       list to operate
 339  * @param   unserializer_fun    pointer to the actual unserializer function
 340  * @return      0 if the attribute was successfully set; -1 otherwise
 341  *
 342  * @see     element_unserializer()
 343  * @see     list_dump_filedescriptor()
 344  * @see     list_restore_filedescriptor()
 345  */
 346 int list_attributes_unserializer(list_t *restrict l, element_unserializer unserializer_fun);
 347
 348 /**
 349  * append data at the end of the list.
 350  *
 351  * This function is useful for adding elements with a FIFO/queue policy.
 352  *
 353  * @param l     list to operate
 354  * @param data  pointer to user data to append
 355  *
 356  * @return      1 for success. < 0 for failure
 357  */
 358 int list_append(list_t *restrict l, const void *data);
 359
 360 /**
 361  * insert data in the head of the list.
 362  *
 363  * This function is useful for adding elements with a LIFO/Stack policy.
 364  *
 365  * @param l     list to operate
 366  * @param data  pointer to user data to append
 367  *
 368  * @return      1 for success. < 0 for failure
 369  */
 370 int list_prepend(list_t *restrict l, const void *restrict data);
 371
 372 /**
 373  * extract the element in the top of the list.
 374  *
 375  * This function is for using a list with a FIFO/queue policy.
 376  *
 377  * @param l     list to operate
 378  * @return      reference to user datum, or NULL on errors
 379  */
 380 void *list_fetch(list_t *restrict l);
 381
 382 /**
 383  * retrieve an element at a given position.
 384  *
 385  * @param l     list to operate
 386  * @param pos   [0,size-1] position index of the element wanted
 387  * @return      reference to user datum, or NULL on errors
 388  */
 389 void *list_get_at(const list_t *restrict l, unsigned int pos);
 390
 391 /**
 392  * return the maximum element of the list.
 393  *
 394  * @warning Requires a comparator function to be set for the list.
 395  *
 396  * Returns the maximum element with respect to the comparator function output.
 397  *
 398  * @see list_attributes_comparator()
 399  *
 400  * @param l     list to operate
 401  * @return      the reference to the element, or NULL
 402  */
 403 void *list_get_max(const list_t *restrict l);
 404
 405 /**
 406  * return the minimum element of the list.
 407  *
 408  * @warning Requires a comparator function to be set for the list.
 409  *
 410  * Returns the minimum element with respect to the comparator function output.
 411  *
 412  * @see list_attributes_comparator()
 413  *
 414  * @param l     list to operate
 415  * @return      the reference to the element, or NULL
 416  */
 417 void *list_get_min(const list_t *restrict l);
 418
 419 /**
 420  * retrieve and remove from list an element at a given position.
 421  *
 422  * @param l     list to operate
 423  * @param pos   [0,size-1] position index of the element wanted
 424  * @return      reference to user datum, or NULL on errors
 425  */
 426 void *list_extract_at(list_t *restrict l, unsigned int pos);
 427
 428 /**
 429  * insert an element at a given position.
 430  *
 431  * @param l     list to operate
 432  * @param data  reference to data to be inserted
 433  * @param pos   [0,size-1] position index to insert the element at
 434  * @return      positive value on success. Negative on failure
 435  */
 436 int list_insert_at(list_t *restrict l, const void *data, unsigned int pos);
 437
 438 /**
 439  * expunge the first found given element from the list.
 440  *
 441  * Inspects the given list looking for the given element; if the element
 442  * is found, it is removed. Only the first occurence is removed.
 443  * If a comparator function was not set, elements are compared by reference.
 444  * Otherwise, the comparator is used to match the element.
 445  *
 446  * @param l     list to operate
 447  * @param data  reference of the element to search for
 448  * @return      0 on success. Negative value on failure
 449  *
 450  * @see list_attributes_comparator()
 451  * @see list_delete_at()
 452  */
 453 int list_delete(list_t *restrict l, const void *data);
 454
 455 /**
 456  * expunge an element at a given position from the list.
 457  *
 458  * @param l     list to operate
 459  * @param pos   [0,size-1] position index of the element to be deleted
 460  * @return      0 on success. Negative value on failure
 461  */
 462 int list_delete_at(list_t *restrict l, unsigned int pos);
 463
 464 /**
 465  * expunge an array of elements from the list, given their position range.
 466  *
 467  * @param l     list to operate
 468  * @param posstart  [0,size-1] position index of the first element to be deleted
 469  * @param posend    [posstart,size-1] position of the last element to be deleted
 470  * @return      the number of elements successfully removed on success, <0 on error
 471  */
 472 int list_delete_range(list_t *restrict l, unsigned int posstart, unsigned int posend);
 473
 474 /**
 475  * clear all the elements off of the list.
 476  *
 477  * The element datums will not be freed.
 478  *
 479  * @see list_delete_range()
 480  * @see list_size()
 481  *
 482  * @param l     list to operate
 483  * @return      the number of elements removed on success, <0 on error
 484  */
 485 int list_clear(list_t *restrict l);
 486
 487 /**
 488  * inspect the number of elements in the list.
 489  *
 490  * @param l     list to operate
 491  * @return      number of elements currently held by the list
 492  */
 493 unsigned int list_size(const list_t *restrict l);
 494
 495 /**
 496  * inspect whether the list is empty.
 497  *
 498  * @param l     list to operate
 499  * @return      0 iff the list is not empty
 500  *
 501  * @see list_size()
 502  */
 503 int list_empty(const list_t *restrict l);
 504
 505 /**
 506  * find the position of an element in a list.
 507  *
 508  * @warning Requires a comparator function to be set for the list.
 509  *
 510  * Inspects the given list looking for the given element; if the element
 511  * is found, its position into the list is returned.
 512  * Elements are inspected comparing references if a comparator has not been
 513  * set. Otherwise, the comparator is used to find the element.
 514  *
 515  * @param l     list to operate
 516  * @param data  reference of the element to search for
 517  * @return      position of element in the list, or <0 if not found
 518  *
 519  * @see list_attributes_comparator()
 520  * @see list_get_at()
 521  */
 522 int list_locate(const list_t *restrict l, const void *data);
 523
 524 /**
 525  * returns an element given an indicator.
 526  *
 527  * @warning Requires a seeker function to be set for the list.
 528  *
 529  * Inspect the given list looking with the seeker if an element matches
 530  * an indicator. If such element is found, the reference to the element
 531  * is returned.
 532  *
 533  * @param l     list to operate
 534  * @param indicator indicator data to pass to the seeker along with elements
 535  * @return      reference to the element accepted by the seeker, or NULL if none found
 536  */
 537 void *list_seek(list_t *restrict l, const void *indicator);
 538
 539 /**
 540  * inspect whether some data is member of the list.
 541  *
 542  * @warning Requires a comparator function to be set for the list.
 543  *
 544  * By default, a per-reference comparison is accomplished. That is,
 545  * the data is in list if any element of the list points to the same
 546  * location of data.
 547  * A "semantic" comparison is accomplished, otherwise, if a comparator
 548  * function has been set previously, with list_attributes_comparator();
 549  * in which case, the given data reference is believed to be in list iff
 550  * comparator_fun(elementdata, userdata) == 0 for any element in the list.
 551  *
 552  * @param l     list to operate
 553  * @param data  reference to the data to search
 554  * @return      0 iff the list does not contain data as an element
 555  *
 556  * @see list_attributes_comparator()
 557  */
 558 int list_contains(const list_t *restrict l, const void *data);
 559
 560 /**
 561  * concatenate two lists
 562  *
 563  * Concatenates one list with another, and stores the result into a
 564  * user-provided list object, which must be different from both the
 565  * lists to concatenate. Attributes from the original lists are not
 566  * cloned.
 567  * The destination list referred is threated as virgin room: if it
 568  * is an existing list containing elements, memory leaks will happen.
 569  * It is OK to specify the same list twice as source, for "doubling"
 570  * it in the destination.
 571  *
 572  * @param l1    base list
 573  * @param l2    list to append to the base
 574  * @param dest  reference to the destination list
 575  * @return      0 for success, -1 for errors
 576  */
 577 int list_concat(const list_t *l1, const list_t *l2, list_t *restrict dest);
 578
 579 /**
 580  * sort list elements.
 581  *
 582  * @warning Requires a comparator function to be set for the list.
 583  *
 584  * Sorts the list in ascending or descending order as specified by the versus
 585  * flag. The algorithm chooses autonomously what algorithm is best suited for
 586  * sorting the list wrt its current status.
 587  *
 588  * @param l     list to operate
 589  * @param versus positive: order small to big; negative: order big to small
 590  * @return      0 iff sorting was successful
 591  *
 592  * @see list_attributes_comparator()
 593  */
 594 int list_sort(list_t *restrict l, int versus);
 595
 596 /**
 597  * start an iteration session.
 598  *
 599  * This function prepares the list to be iterated.
 600  *
 601  * @param l     list to operate
 602  * @return              0 if the list cannot be currently iterated. >0 otherwise
 603  *
 604  * @see list_iterator_stop()
 605  */
 606 int list_iterator_start(list_t *restrict l);
 607
 608 /**
 609  * return the next element in the iteration session.
 610  *
 611  * @param l     list to operate
 612  * @return              element datum, or NULL on errors
 613  */
 614 void *list_iterator_next(list_t *restrict l);
 615
 616 /**
 617  * inspect whether more elements are available in the iteration session.
 618  *
 619  * @param l     list to operate
 620  * @return      0 iff no more elements are available.
 621  */
 622 int list_iterator_hasnext(const list_t *restrict l);
 623
 624 /**
 625  * end an iteration session.
 626  *
 627  * @param l     list to operate
 628  * @return      0 iff the iteration session cannot be stopped
 629  */
 630 int list_iterator_stop(list_t *restrict l);
 631
 632 /**
 633  * return the hash of the current status of the list.
 634  *
 635  * @param l     list to operate
 636  * @param hash  where the resulting hash is put
 637  *
 638  * @return      0 for success; <0 for failure
 639  */
 640 int list_hash(const list_t *restrict l, list_hash_t *restrict hash);
 641
 642 #ifndef SIMCLIST_NO_DUMPRESTORE
 643 /**
 644  * get meta informations on a list dump on filedescriptor.
 645  *
 646  * [ advanced function ]
 647  *
 648  * Extracts the meta information from a SimCList dump located in a file
 649  * descriptor. The file descriptor must be open and positioned at the
 650  * beginning of the SimCList dump block.
 651  *
 652  * @param fd        file descriptor to get metadata from
 653  * @param info      reference to a dump metainformation structure to fill
 654  * @return          0 for success; <0 for failure
 655  *
 656  * @see list_dump_filedescriptor()
 657  */
 658 int list_dump_getinfo_filedescriptor(int fd, list_dump_info_t *restrict info);
 659
 660 /**
 661  * get meta informations on a list dump on file.
 662  *
 663  * [ advanced function ]
 664  *
 665  * Extracts the meta information from a SimCList dump located in a file.
 666  *
 667  * @param filename  filename of the file to fetch from
 668  * @param info      reference to a dump metainformation structure to fill
 669  * @return          0 for success; <0 for failure
 670  *
 671  * @see list_dump_filedescriptor()
 672  */
 673 int list_dump_getinfo_file(const char *restrict filename, list_dump_info_t *restrict info);
 674
 675 /**
 676  * dump the list into an open, writable file descriptor.
 677  *
 678  * This function "dumps" the list to a persistent storage so it can be
 679  * preserved across process terminations.
 680  * When called, the file descriptor must be open for writing and positioned
 681  * where the serialized data must begin. It writes its serialization of the
 682  * list in a form which is portable across different architectures. Dump can
 683  * be safely performed on stream-only (non seekable) descriptors. The file
 684  * descriptor is not closed at the end of the operations.
 685  *
 686  * To use dump functions, either of these conditions must be satisfied:
 687  *      -# a metric function has been specified with list_attributes_copy()
 688  *      -# a serializer function has been specified with list_attributes_serializer()
 689  *
 690  * If a metric function has been specified, each element of the list is dumped
 691  * as-is from memory, copying it from its pointer for its length down to the
 692  * file descriptor. This might have impacts on portability of the dump to
 693  * different architectures.
 694  *
 695  * If a serializer function has been specified, its result for each element is
 696  * dumped to the file descriptor.
 697  *
 698  *
 699  * @param l     list to operate
 700  * @param fd    file descriptor to write to
 701  * @param len   location to store the resulting length of the dump (bytes), or NULL
 702  *
 703  * @return      0 if successful; -1 otherwise
 704  *
 705  * @see element_serializer()
 706  * @see list_attributes_copy()
 707  * @see list_attributes_serializer()
 708  */
 709 int list_dump_filedescriptor(const list_t *restrict l, int fd, size_t *restrict len);
 710
 711 /**
 712  * dump the list to a file name.
 713  *
 714  * This function creates a filename and dumps the current content of the list
 715  * to it. If the file exists it is overwritten. The number of bytes written to
 716  * the file can be returned in a specified argument.
 717  *
 718  * @param l     list to operate
 719  * @param filename    filename to write to
 720  * @param len   location to store the resulting length of the dump (bytes), or NULL
 721  *
 722  * @return      0 if successful; -1 otherwise
 723  *
 724  * @see list_attributes_copy()
 725  * @see element_serializer()
 726  * @see list_attributes_serializer()
 727  * @see list_dump_filedescriptor()
 728  * @see list_restore_file()
 729  *
 730  * This function stores a representation of the list
 731  */
 732 int list_dump_file(const list_t *restrict l, const char *restrict filename, size_t *restrict len);
 733
 734 /**
 735  * restore the list from an open, readable file descriptor to memory.
 736  *
 737  * This function is the "inverse" of list_dump_filedescriptor(). It restores
 738  * the list content from a (open, read-ready) file descriptor to memory. An
 739  * unserializer might be needed to restore elements from the persistent
 740  * representation back into memory-consistent format. List attributes can not
 741  * be restored and must be set manually.
 742  *
 743  * @see list_dump_filedescriptor()
 744  * @see list_attributes_serializer()
 745  * @see list_attributes_unserializer()
 746  *
 747  * @param l     list to restore to
 748  * @param fd    file descriptor to read from.
 749  * @param len   location to store the length of the dump read (bytes), or NULL
 750  * @return      0 if successful; -1 otherwise
 751  */
 752 int list_restore_filedescriptor(list_t *restrict l, int fd, size_t *restrict len);
 753
 754 /**
 755  * restore the list from a file name.
 756  *
 757  * This function restores the content of a list from a file into memory. It is
 758  * the inverse of list_dump_file().
 759  *
 760  * @see element_unserializer()
 761  * @see list_attributes_unserializer()
 762  * @see list_dump_file()
 763  * @see list_restore_filedescriptor()
 764  *
 765  * @param l         list to restore to
 766  * @param filename  filename to read data from
 767  * @param len       location to store the length of the dump read (bytes), or NULL
 768  * @return          0 if successful; -1 otherwise
 769  */
 770 int list_restore_file(list_t *restrict l, const char *restrict filename, size_t *len);
 771 #endif
 772
 773 /* ready-made comparators, meters and hash computers */
 774                                 /* comparator functions */
 775 /**
 776  * ready-made comparator for int8_t elements.
 777  * @see list_attributes_comparator()
 778  */
 779 int list_comparator_int8_t(const void *a, const void *b);
 780
 781 /**
 782  * ready-made comparator for int16_t elements.
 783  * @see list_attributes_comparator()
 784  */
 785 int list_comparator_int16_t(const void *a, const void *b);
 786
 787 /**
 788  * ready-made comparator for int32_t elements.
 789  * @see list_attributes_comparator()
 790  */
 791 int list_comparator_int32_t(const void *a, const void *b);
 792
 793 /**
 794  * ready-made comparator for int64_t elements.
 795  * @see list_attributes_comparator()
 796  */
 797 int list_comparator_int64_t(const void *a, const void *b);
 798
 799 /**
 800  * ready-made comparator for uint8_t elements.
 801  * @see list_attributes_comparator()
 802  */
 803 int list_comparator_uint8_t(const void *a, const void *b);
 804
 805 /**
 806  * ready-made comparator for uint16_t elements.
 807  * @see list_attributes_comparator()
 808  */
 809 int list_comparator_uint16_t(const void *a, const void *b);
 810
 811 /**
 812  * ready-made comparator for uint32_t elements.
 813  * @see list_attributes_comparator()
 814  */
 815 int list_comparator_uint32_t(const void *a, const void *b);
 816
 817 /**
 818  * ready-made comparator for uint64_t elements.
 819  * @see list_attributes_comparator()
 820  */
 821 int list_comparator_uint64_t(const void *a, const void *b);
 822
 823 /**
 824  * ready-made comparator for float elements.
 825  * @see list_attributes_comparator()
 826  */
 827 int list_comparator_float(const void *a, const void *b);
 828
 829 /**
 830  * ready-made comparator for double elements.
 831  * @see list_attributes_comparator()
 832  */
 833 int list_comparator_double(const void *a, const void *b);
 834
 835 /**
 836  * ready-made comparator for string elements.
 837  * @see list_attributes_comparator()
 838  */
 839 int list_comparator_string(const void *a, const void *b);
 840
 841                                 /*          metric functions        */
 842 /**
 843  * ready-made metric function for int8_t elements.
 844  * @see list_attributes_copy()
 845  */
 846 size_t list_meter_int8_t(const void *el);
 847
 848 /**
 849  * ready-made metric function for int16_t elements.
 850  * @see list_attributes_copy()
 851  */
 852 size_t list_meter_int16_t(const void *el);
 853
 854 /**
 855  * ready-made metric function for int32_t elements.
 856  * @see list_attributes_copy()
 857  */
 858 size_t list_meter_int32_t(const void *el);
 859
 860 /**
 861  * ready-made metric function for int64_t elements.
 862  * @see list_attributes_copy()
 863  */
 864 size_t list_meter_int64_t(const void *el);
 865
 866 /**
 867  * ready-made metric function for uint8_t elements.
 868  * @see list_attributes_copy()
 869  */
 870 size_t list_meter_uint8_t(const void *el);
 871
 872 /**
 873  * ready-made metric function for uint16_t elements.
 874  * @see list_attributes_copy()
 875  */
 876 size_t list_meter_uint16_t(const void *el);
 877
 878 /**
 879  * ready-made metric function for uint32_t elements.
 880  * @see list_attributes_copy()
 881  */
 882 size_t list_meter_uint32_t(const void *el);
 883
 884 /**
 885  * ready-made metric function for uint64_t elements.
 886  * @see list_attributes_copy()
 887  */
 888 size_t list_meter_uint64_t(const void *el);
 889
 890 /**
 891  * ready-made metric function for float elements.
 892  * @see list_attributes_copy()
 893  */
 894 size_t list_meter_float(const void *el);
 895
 896 /**
 897  * ready-made metric function for double elements.
 898  * @see list_attributes_copy()
 899  */
 900 size_t list_meter_double(const void *el);
 901
 902 /**
 903  * ready-made metric function for string elements.
 904  * @see list_attributes_copy()
 905  */
 906 size_t list_meter_string(const void *el);
 907
 908                                 /*          hash functions          */
 909 /**
 910  * ready-made hash function for int8_t elements.
 911  * @see list_attributes_hash_computer()
 912  */
 913 list_hash_t list_hashcomputer_int8_t(const void *el);
 914
 915 /**
 916  * ready-made hash function for int16_t elements.
 917  * @see list_attributes_hash_computer()
 918  */
 919 list_hash_t list_hashcomputer_int16_t(const void *el);
 920
 921 /**
 922  * ready-made hash function for int32_t elements.
 923  * @see list_attributes_hash_computer()
 924  */
 925 list_hash_t list_hashcomputer_int32_t(const void *el);
 926
 927 /**
 928  * ready-made hash function for int64_t elements.
 929  * @see list_attributes_hash_computer()
 930  */
 931 list_hash_t list_hashcomputer_int64_t(const void *el);
 932
 933 /**
 934  * ready-made hash function for uint8_t elements.
 935  * @see list_attributes_hash_computer()
 936  */
 937 list_hash_t list_hashcomputer_uint8_t(const void *el);
 938
 939 /**
 940  * ready-made hash function for uint16_t elements.
 941  * @see list_attributes_hash_computer()
 942  */
 943 list_hash_t list_hashcomputer_uint16_t(const void *el);
 944
 945 /**
 946  * ready-made hash function for uint32_t elements.
 947  * @see list_attributes_hash_computer()
 948  */
 949 list_hash_t list_hashcomputer_uint32_t(const void *el);
 950
 951 /**
 952  * ready-made hash function for uint64_t elements.
 953  * @see list_attributes_hash_computer()
 954  */
 955 list_hash_t list_hashcomputer_uint64_t(const void *el);
 956
 957 /**
 958  * ready-made hash function for float elements.
 959  * @see list_attributes_hash_computer()
 960  */
 961 list_hash_t list_hashcomputer_float(const void *el);
 962
 963 /**
 964  * ready-made hash function for double elements.
 965  * @see list_attributes_hash_computer()
 966  */
 967 list_hash_t list_hashcomputer_double(const void *el);
 968
 969 /**
 970  * ready-made hash function for string elements.
 971  * @see list_attributes_hash_computer()
 972  */
 973 list_hash_t list_hashcomputer_string(const void *el);
 974
 975 #ifdef __cplusplus
 976 }
 977 #endif
 978
 979 #endif
 980