gdb/dictionary.h

   1 /* Routines for name->symbol lookups in GDB.
   2
   3    Copyright (C) 2003-2022 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 multi-language dictionaries; only dictionary.c should
  29    know about its innards.  */
  30
  31 struct multidictionary;
  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    multi-language dictionaries.  */
  42
  43 /* Create a multi-language dictionary of symbols 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 multidictionary *
  48   mdict_create_hashed (struct obstack *obstack,
  49                        const struct pending *symbol_list);
  50
  51 /* Create a multi-language dictionary of symbols, implemented
  52    via a hashtable that grows as necessary.  The initial dictionary of
  53    LANGUAGE is empty; to add symbols to it, call mdict_add_symbol().
  54    Call mdict_free() when you're done with it.  */
  55
  56 extern struct multidictionary *
  57   mdict_create_hashed_expandable (enum language language);
  58
  59 /* Create a multi-language dictionary of symbols, implemented
  60    via a fixed-size array.  All memory it uses is allocated on
  61    OBSTACK; the environment is initialized from the SYMBOL_LIST.  The
  62    symbols are ordered in the same order that they're found in
  63    SYMBOL_LIST.  */
  64
  65 extern struct multidictionary *
  66   mdict_create_linear (struct obstack *obstack,
  67                        const struct pending *symbol_list);
  68
  69 /* Create a multi-language dictionary of symbols, implemented
  70    via an array that grows as necessary.  The multidictionary initially
  71    contains a single empty dictionary of LANGUAGE; to add symbols to it,
  72    call mdict_add_symbol().  Call mdict_free() when you're done with it.  */
  73
  74 extern struct multidictionary *
  75   mdict_create_linear_expandable (enum language language);
  76
  77 /* The functions providing the interface to multi-language dictionaries.
  78    Note that the most common parts of the interface, namely symbol lookup,
  79    are only provided via iterator functions.  */
  80
  81 /* Free the memory used by a multidictionary that's not on an obstack.  (If
  82    any.)  */
  83
  84 extern void mdict_free (struct multidictionary *mdict);
  85
  86 /* Add a symbol to an expandable multidictionary.  */
  87
  88 extern void mdict_add_symbol (struct multidictionary *mdict,
  89                               struct symbol *sym);
  90
  91 /* Utility to add a list of symbols to a multidictionary.  */
  92
  93 extern void mdict_add_pending (struct multidictionary *mdict,
  94                                const struct pending *symbol_list);
  95
  96 /* A type containing data that is used when iterating over all symbols
  97    in a dictionary.  Don't ever look at its innards; this type would
  98    be opaque if we didn't need to be able to allocate it on the
  99    stack.  */
 100
 101 struct dict_iterator
 102 {
 103   /* The dictionary that this iterator is associated to.  */
 104   const struct dictionary *dict;
 105   /* The next two members are data that is used in a way that depends
 106      on DICT's implementation type.  */
 107   int index;
 108   struct symbol *current;
 109 };
 110
 111 /* The multi-language dictionary iterator.  Like dict_iterator above,
 112    these contents should be considered private.  */
 113
 114 struct mdict_iterator
 115 {
 116   /* The multidictionary with whcih this iterator is associated.  */
 117   const struct multidictionary *mdict;
 118
 119   /* The iterator used to iterate through individual dictionaries.  */
 120   struct dict_iterator iterator;
 121
 122   /* The current index of the dictionary being iterated over.  */
 123   unsigned short current_idx;
 124 };
 125
 126 /* Initialize ITERATOR to point at the first symbol in MDICT, and
 127    return that first symbol, or NULL if MDICT is empty.  */
 128
 129 extern struct symbol *
 130   mdict_iterator_first (const struct multidictionary *mdict,
 131                         struct mdict_iterator *miterator);
 132
 133 /* Advance MITERATOR, and return the next symbol, or NULL if there are
 134    no more symbols.  Don't call this if you've previously received
 135    NULL from mdict_iterator_first or mdict_iterator_next on this
 136    iteration.  */
 137
 138 extern struct symbol *mdict_iterator_next (struct mdict_iterator *miterator);
 139
 140 /* Initialize MITERATOR to point at the first symbol in MDICT whose
 141    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 *
 147   mdict_iter_match_first (const struct multidictionary *mdict,
 148                           const lookup_name_info &name,
 149                           struct mdict_iterator *miterator);
 150
 151 /* Advance MITERATOR to point at the next symbol in MDICT whose
 152    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    mdict_iterator_match_first or mdict_iterator_match_next on this
 156    iteration.  And don't call it unless MITERATOR was created by a
 157    previous call to mdict_iter_match_first with the same NAME and COMPARE.  */
 158
 159 extern struct symbol *mdict_iter_match_next (const lookup_name_info &name,
 160                                              struct mdict_iterator *miterator);
 161
 162 /* Return some notion of the size of the multidictionary: the number of
 163    symbols if we have that, the number of hash buckets otherwise.  */
 164
 165 extern int mdict_size (const struct multidictionary *mdict);
 166
 167 /* Macro to loop through all symbols in a dictionary DICT, in no
 168    particular order.  ITER is a struct dict_iterator (NOTE: __not__ a
 169    struct dict_iterator *), and SYM points to the current symbol.
 170
 171    It's implemented as a single loop, so you can terminate the loop
 172    early by a break if you desire.  */
 173
 174 #define ALL_DICT_SYMBOLS(dict, iter, sym)                       \
 175         for ((sym) = mdict_iterator_first ((dict), &(iter));    \
 176              (sym);                                             \
 177              (sym) = mdict_iterator_next (&(iter)))
 178
 179 #endif /* DICTIONARY_H */