gdb/dictionary.h

   1 /* Routines for name->symbol lookups in GDB.
   2
   3    Copyright (C) 2003, 2007, 2008, 2009, 2010, 2011
   4    Free Software Foundation, Inc.
   5
   6    Contributed by David Carlton <carlton@bactrian.org> and by Kealia,
   7    Inc.
   8
   9    This file is part of GDB.
  10
  11    This program is free software; you can redistribute it and/or modify
  12    it under the terms of the GNU General Public License as published by
  13    the Free Software Foundation; either version 3 of the License, or
  14    (at your option) any later version.
  15
  16    This program is distributed in the hope that it will be useful,
  17    but WITHOUT ANY WARRANTY; without even the implied warranty of
  18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19    GNU General Public License for more details.
  20
  21    You should have received a copy of the GNU General Public License
  22    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  23
  24 #ifndef DICTIONARY_H
  25 #define DICTIONARY_H
  26
  27 #include "symfile.h"
  28
  29 /* An opaque type for dictionaries; only dictionary.c should know
  30    about its innards.  */
  31
  32 struct dictionary;
  33
  34 /* Other types needed for declarations.  */
  35
  36 struct symbol;
  37 struct obstack;
  38 struct pending;
  39
  40
  41 /* The creation functions for various implementations of
  42    dictionaries.  */
  43
  44 /* Create a dictionary implemented via a fixed-size hashtable.  All
  45    memory it uses is allocated on OBSTACK; the environment is
  46    initialized from SYMBOL_LIST.  */
  47
  48 extern struct dictionary *dict_create_hashed (struct obstack *obstack,
  49                                               const struct pending
  50                                               *symbol_list);
  51
  52 /* Create a dictionary implemented via a hashtable that grows as
  53    necessary.  The dictionary is initially empty; to add symbols to
  54    it, call dict_add_symbol().  Call dict_free() when you're done with
  55    it.  */
  56
  57 extern struct dictionary *dict_create_hashed_expandable (void);
  58
  59 /* Create a dictionary implemented via a fixed-size array.  All memory
  60    it uses is allocated on OBSTACK; the environment is initialized
  61    from the SYMBOL_LIST.  The symbols are ordered in the same order
  62    that they're found in SYMBOL_LIST.  */
  63
  64 extern struct dictionary *dict_create_linear (struct obstack *obstack,
  65                                               const struct pending
  66                                               *symbol_list);
  67
  68 /* Create a dictionary implemented via an array that grows as
  69    necessary.  The dictionary is initially empty; to add symbols to
  70    it, call dict_add_symbol().  Call dict_free() when you're done with
  71    it.  */
  72
  73 extern struct dictionary *dict_create_linear_expandable (void);
  74
  75
  76 /* The functions providing the interface to dictionaries.  Note that
  77    the most common parts of the interface, namely symbol lookup, are
  78    only provided via iterator functions.  */
  79
  80 /* Free the memory used by a dictionary that's not on an obstack.  (If
  81    any.)  */
  82
  83 extern void dict_free (struct dictionary *dict);
  84
  85 /* Add a symbol to an expandable dictionary.  */
  86
  87 extern void dict_add_symbol (struct dictionary *dict, struct symbol *sym);
  88
  89 /* Is the dictionary empty?  */
  90
  91 extern int dict_empty (struct dictionary *dict);
  92
  93 /* A type containing data that is used when iterating over all symbols
  94    in a dictionary.  Don't ever look at its innards; this type would
  95    be opaque if we didn't need to be able to allocate it on the
  96    stack.  */
  97
  98 struct dict_iterator
  99 {
 100   /* The dictionary that this iterator is associated to.  */
 101   const struct dictionary *dict;
 102   /* The next two members are data that is used in a way that depends
 103      on DICT's implementation type.  */
 104   int index;
 105   struct symbol *current;
 106 };
 107
 108 /* Initialize ITERATOR to point at the first symbol in DICT, and
 109    return that first symbol, or NULL if DICT is empty.  */
 110
 111 extern struct symbol *dict_iterator_first (const struct dictionary *dict,
 112                                            struct dict_iterator *iterator);
 113
 114 /* Advance ITERATOR, and return the next symbol, or NULL if there are
 115    no more symbols.  Don't call this if you've previously received
 116    NULL from dict_iterator_first or dict_iterator_next on this
 117    iteration.  */
 118
 119 extern struct symbol *dict_iterator_next (struct dict_iterator *iterator);
 120
 121 /* Initialize ITERATOR to point at the first symbol in DICT whose
 122    SYMBOL_SEARCH_NAME is NAME (as tested using strcmp_iw), and return
 123    that first symbol, or NULL if there are no such symbols.  */
 124
 125 extern struct symbol *dict_iter_name_first (const struct dictionary *dict,
 126                                             const char *name,
 127                                             struct dict_iterator *iterator);
 128
 129 /* Advance ITERATOR to point at the next symbol in DICT whose
 130    SYMBOL_SEARCH_NAME is NAME (as tested using strcmp_iw), or NULL if
 131    there are no more such symbols.  Don't call this if you've
 132    previously received NULL from dict_iterator_first or
 133    dict_iterator_next on this iteration.  And don't call it unless
 134    ITERATOR was created by a previous call to dict_iter_name_first
 135    with the same NAME.  */
 136
 137 extern struct symbol *dict_iter_name_next (const char *name,
 138                                            struct dict_iterator *iterator);
 139
 140 /* Initialize ITERATOR to point at the first symbol in DICT whose
 141    SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (which must use
 142    the same conventions as strcmp_iw and be compatible with any
 143    dictionary hashing function), and return that first symbol, or NULL
 144    if there are no such symbols.  */
 145
 146 extern struct symbol *dict_iter_match_first (const struct dictionary *dict,
 147                                              const char *name,
 148                                              symbol_compare_ftype *compare,
 149                                              struct dict_iterator *iterator);
 150
 151 /* Advance ITERATOR to point at the next symbol in DICT whose
 152    SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (see
 153    dict_iter_match_first), or NULL if there are no more such symbols.
 154    Don't call this if you've previously received NULL from
 155    dict_iterator_match_first or dict_iterator_match_next on this
 156    iteration.  And don't call it unless ITERATOR was created by a
 157    previous call to dict_iter_match_first with the same NAME and COMPARE.  */
 158
 159 extern struct symbol *dict_iter_match_next (const char *name,
 160                                             symbol_compare_ftype *compare,
 161                                             struct dict_iterator *iterator);
 162
 163 /* Return some notion of the size of the dictionary: the number of
 164    symbols if we have that, the number of hash buckets otherwise.  */
 165
 166 extern int dict_size (const struct dictionary *dict);
 167
 168 /* Macro to loop through all symbols in a dictionary DICT, in no
 169    particular order.  ITER is a struct dict_iterator (NOTE: __not__ a
 170    struct dict_iterator *), and SYM points to the current symbol.
 171
 172    It's implemented as a single loop, so you can terminate the loop
 173    early by a break if you desire.  */
 174
 175 #define ALL_DICT_SYMBOLS(dict, iter, sym)                       \
 176         for ((sym) = dict_iterator_first ((dict), &(iter));     \
 177              (sym);                                             \
 178              (sym) = dict_iterator_next (&(iter)))
 179
 180 #endif /* DICTIONARY_H */