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 981