gdb/dictionary.h

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