xref: /netbsd-src/external/gpl3/gdb.old/dist/gdb/dictionary.h (revision 924795e69c8bb3f17afd8fcbb799710cc1719dc4)
1 /* Routines for name->symbol lookups in GDB.
2 
3    Copyright (C) 2003-2020 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 */
180