src/pulsecore/idxset.h

   1 #ifndef fooidxsethfoo
   2 #define fooidxsethfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of PulseAudio.
   8
   9   Copyright 2004-2006 Lennart Poettering
  10   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
  11
  12   PulseAudio is free software; you can redistribute it and/or modify
  13   it under the terms of the GNU Lesser General Public License as
  14   published by the Free Software Foundation; either version 2.1 of the
  15   License, or (at your option) any later version.
  16
  17   PulseAudio is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public
  23   License along with PulseAudio; if not, write to the Free Software
  24   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  25   USA.
  26 ***/
  27
  28 #include <inttypes.h>
  29
  30 /* A combination of a set and a dynamic array. Entries are indexable
  31  * both through a numeric automatically generated index and the entry's
  32  * data pointer. As usual, memory management is the user's job. */
  33
  34 /* A special index value denoting the invalid index. */
  35 #define PA_IDXSET_INVALID ((uint32_t) -1)
  36
  37 /* Generic implementations for hash and comparison functions. Just
  38  * compares the pointer or calculates the hash value directly from the
  39  * pointer value. */
  40 unsigned pa_idxset_trivial_hash_func(const void *p);
  41 int pa_idxset_trivial_compare_func(const void *a, const void *b);
  42
  43 /* Generic implementations for hash and comparison functions for strings. */
  44 unsigned pa_idxset_string_hash_func(const void *p);
  45 int pa_idxset_string_compare_func(const void *a, const void *b);
  46
  47 typedef unsigned (*pa_hash_func_t)(const void *p);
  48 typedef int (*pa_compare_func_t)(const void *a, const void *b);
  49
  50 typedef struct pa_idxset pa_idxset;
  51
  52 /* Instantiate a new idxset with the specified hash and comparison functions */
  53 pa_idxset* pa_idxset_new(pa_hash_func_t hash_func, pa_compare_func_t compare_func);
  54
  55 /* Free the idxset. When the idxset is not empty the specified function is called for every entry contained */
  56 void pa_idxset_free(pa_idxset *s, void (*free_func) (void *p, void *userdata), void *userdata);
  57
  58 /* Store a new item in the idxset. The index of the item is returned in *idx */
  59 int pa_idxset_put(pa_idxset*s, void *p, uint32_t *idx);
  60
  61 /* Get the entry by its idx */
  62 void* pa_idxset_get_by_index(pa_idxset*s, uint32_t idx);
  63
  64 /* Get the entry by its data. The idx is returned in *index */
  65 void* pa_idxset_get_by_data(pa_idxset*s, const void *p, uint32_t *idx);
  66
  67 /* Similar to pa_idxset_get_by_index(), but removes the entry from the idxset. */
  68 void* pa_idxset_remove_by_index(pa_idxset*s, uint32_t idx);
  69
  70 /* Similar to pa_idxset_get_by_data(), but removes the entry from the idxset */
  71 void* pa_idxset_remove_by_data(pa_idxset*s, const void *p, uint32_t *idx);
  72
  73 /* This may be used to iterate through all entries. When called with
  74    an invalid index value it returns the first entry, otherwise the
  75    next following. The function is best called with *idx =
  76    PA_IDXSET_VALID first. It is safe to manipulate the idxset between
  77    the calls. It is not guaranteed that all entries have already been
  78    returned before the an entry is returned the second time.*/
  79 void* pa_idxset_rrobin(pa_idxset *s, uint32_t *idx);
  80
  81 /* Return the oldest entry in the idxset. Fill in its index in *idx. */
  82 void* pa_idxset_first(pa_idxset *s, uint32_t *idx);
  83
  84 /* Return the entry following the entry indexed by *idx.  After the
  85  * call *index contains the index of the returned
  86  * object. pa_idxset_first() and pa_idxset_next() may be used to
  87  * iterate through the set.*/
  88 void *pa_idxset_next(pa_idxset *s, uint32_t *idx);
  89
  90 /* Call a function for every item in the set. If the callback function
  91    returns -1, the loop is terminated. If *del is set to non-zero that
  92    specific item is removed. It is not safe to call any other
  93    functions on the idxset while pa_idxset_foreach is executed. */
  94 int pa_idxset_foreach(pa_idxset*s, int (*func)(void *p, uint32_t idx, int *del, void*userdata), void *userdata);
  95
  96 unsigned pa_idxset_size(pa_idxset*s);
  97
  98 int pa_idxset_isempty(pa_idxset *s);
  99
 100 #endif