simclist.h

/*
 * Copyright (c) 2007,2008 Mij <mij@bitchx.it>
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
 
/*
 * SimCList library. See http://mij.oltrelinux.com/devel/simclist
 */
 
 
#ifndef SIMCLIST_H
#define SIMCLIST_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <inttypes.h>
#include <errno.h>
#include <sys/types.h>
 
#ifndef SIMCLIST_NO_DUMPRESTORE
#   ifndef _WIN32
#       include <sys/time.h>    /* list_dump_info_t's struct timeval */
#   else
#       include <time.h>
#   endif
#endif
 
 
/* Be friend of both C90 and C99 compilers */
#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
    /* "inline" and "restrict" are keywords */
#else
#   define inline           /* inline */
#   define restrict         /* restrict */
#endif
 
 
typedef int32_t list_hash_t;
 
#ifndef SIMCLIST_NO_DUMPRESTORE
typedef struct {
    uint16_t version;           /* dump version */
    struct timeval timestamp;   /* when the list has been dumped, seconds since UNIX epoch */
    uint32_t list_size;
    uint32_t list_numels;
    list_hash_t list_hash;      /* hash of the list when dumped, or 0 if invalid */
    uint32_t dumpsize;
    int consistent;             /* 1 if the dump is verified complete/consistent; 0 otherwise */
} list_dump_info_t;
#endif
 
typedef int (*element_comparator)(const void *a, const void *b);
 
typedef int (*element_seeker)(const void *el, const void *indicator);
 
typedef size_t (*element_meter)(const void *el);
 
typedef list_hash_t (*element_hash_computer)(const void *el);
 
typedef void *(*element_serializer)(const void *restrict el, uint32_t *restrict serializ_len);
 
typedef void *(*element_unserializer)(const void *restrict data, uint32_t *restrict data_len);
 
/* [private-use] list entry -- olds actual user datum */
struct list_entry_s {
    void *data;
 
    /* doubly-linked list service references */
    struct list_entry_s *next;
    struct list_entry_s *prev;
};
 
/* [private-use] list attributes */
struct list_attributes_s {
    /* user-set routine for comparing list elements */
    element_comparator comparator;
    /* user-set routing for seeking elements */
    element_seeker seeker;
    /* user-set routine for determining the length of an element */
    element_meter meter;
    int copy_data;
    /* user-set routine for computing the hash of an element */
    element_hash_computer hasher;
    /* user-set routine for serializing an element */
    element_serializer serializer;
    /* user-set routine for unserializing an element */
    element_unserializer unserializer;
};
 
typedef struct {
    struct list_entry_s *head_sentinel;
    struct list_entry_s *tail_sentinel;
    struct list_entry_s *mid;
 
    unsigned int numels;
 
    /* array of spare elements */
    struct list_entry_s **spareels;
    unsigned int spareelsnum;
 
#ifdef SIMCLIST_WITH_THREADS
    /* how many threads are currently running */
    unsigned int threadcount;
#endif
 
    /* service variables for list iteration */
    int iter_active;
    unsigned int iter_pos;
    struct list_entry_s *iter_curentry;
 
    /* list attributes */
    struct list_attributes_s attrs;
} list_t;
 
int list_init(list_t *restrict l);
 
void list_destroy(list_t *restrict l);
 
int list_attributes_comparator(list_t *restrict l, element_comparator comparator_fun);
 
int list_attributes_seeker(list_t *restrict l, element_seeker seeker_fun);
 
int list_attributes_copy(list_t *restrict l, element_meter metric_fun, int copy_data);
 
int list_attributes_hash_computer(list_t *restrict l, element_hash_computer hash_computer_fun);
 
int list_attributes_serializer(list_t *restrict l, element_serializer serializer_fun);
 
int list_attributes_unserializer(list_t *restrict l, element_unserializer unserializer_fun);
 
int list_append(list_t *restrict l, const void *data);
 
int list_prepend(list_t *restrict l, const void *restrict data);
 
void *list_fetch(list_t *restrict l);
 
void *list_get_at(const list_t *restrict l, unsigned int pos);
 
void *list_get_max(const list_t *restrict l);
 
void *list_get_min(const list_t *restrict l);
 
void *list_extract_at(list_t *restrict l, unsigned int pos);
 
int list_insert_at(list_t *restrict l, const void *data, unsigned int pos);
 
int list_delete(list_t *restrict l, const void *data);
 
int list_delete_at(list_t *restrict l, unsigned int pos);
 
int list_delete_range(list_t *restrict l, unsigned int posstart, unsigned int posend);
 
int list_clear(list_t *restrict l);
 
unsigned int list_size(const list_t *restrict l);
 
int list_empty(const list_t *restrict l);
 
int list_locate(const list_t *restrict l, const void *data);
 
void *list_seek(list_t *restrict l, const void *indicator);
 
int list_contains(const list_t *restrict l, const void *data);
 
int list_concat(const list_t *l1, const list_t *l2, list_t *restrict dest);
 
int list_sort(list_t *restrict l, int versus);
 
int list_iterator_start(list_t *restrict l);
 
void *list_iterator_next(list_t *restrict l);
 
int list_iterator_hasnext(const list_t *restrict l);
 
int list_iterator_stop(list_t *restrict l);
 
int list_hash(const list_t *restrict l, list_hash_t *restrict hash);
 
#ifndef SIMCLIST_NO_DUMPRESTORE
int list_dump_getinfo_filedescriptor(int fd, list_dump_info_t *restrict info);
 
int list_dump_getinfo_file(const char *restrict filename, list_dump_info_t *restrict info);
 
int list_dump_filedescriptor(const list_t *restrict l, int fd, size_t *restrict len);
 
int list_dump_file(const list_t *restrict l, const char *restrict filename, size_t *restrict len);
 
int list_restore_filedescriptor(list_t *restrict l, int fd, size_t *restrict len);
 
int list_restore_file(list_t *restrict l, const char *restrict filename, size_t *len);
#endif
 
/* ready-made comparators, meters and hash computers */
                                /* comparator functions */
int list_comparator_int8_t(const void *a, const void *b);
 
int list_comparator_int16_t(const void *a, const void *b);
 
int list_comparator_int32_t(const void *a, const void *b);
 
int list_comparator_int64_t(const void *a, const void *b);
 
int list_comparator_uint8_t(const void *a, const void *b);
 
int list_comparator_uint16_t(const void *a, const void *b);
 
int list_comparator_uint32_t(const void *a, const void *b);
 
int list_comparator_uint64_t(const void *a, const void *b);
 
int list_comparator_float(const void *a, const void *b);
 
int list_comparator_double(const void *a, const void *b);
 
int list_comparator_string(const void *a, const void *b);
 
                                /*          metric functions        */
size_t list_meter_int8_t(const void *el);
 
size_t list_meter_int16_t(const void *el);
 
size_t list_meter_int32_t(const void *el);
 
size_t list_meter_int64_t(const void *el);
 
size_t list_meter_uint8_t(const void *el);
 
size_t list_meter_uint16_t(const void *el);
 
size_t list_meter_uint32_t(const void *el);
 
size_t list_meter_uint64_t(const void *el);
 
size_t list_meter_float(const void *el);
 
size_t list_meter_double(const void *el);
 
size_t list_meter_string(const void *el);
 
                                /*          hash functions          */
list_hash_t list_hashcomputer_int8_t(const void *el);
 
list_hash_t list_hashcomputer_int16_t(const void *el);
 
list_hash_t list_hashcomputer_int32_t(const void *el);
 
list_hash_t list_hashcomputer_int64_t(const void *el);
 
list_hash_t list_hashcomputer_uint8_t(const void *el);
 
list_hash_t list_hashcomputer_uint16_t(const void *el);
 
list_hash_t list_hashcomputer_uint32_t(const void *el);
 
list_hash_t list_hashcomputer_uint64_t(const void *el);
 
list_hash_t list_hashcomputer_float(const void *el);
 
list_hash_t list_hashcomputer_double(const void *el);
 
list_hash_t list_hashcomputer_string(const void *el);
 
#ifdef __cplusplus
}
#endif
 
#endif