GDB (API)
/home/stan/gdb/src/gdb/dictionary.h
Go to the documentation of this file.
00001 /* Routines for name->symbol lookups in GDB.
00002    
00003    Copyright (C) 2003-2013 Free Software Foundation, Inc.
00004 
00005    Contributed by David Carlton <carlton@bactrian.org> and by Kealia,
00006    Inc.
00007 
00008    This file is part of GDB.
00009 
00010    This program is free software; you can redistribute it and/or modify
00011    it under the terms of the GNU General Public License as published by
00012    the Free Software Foundation; either version 3 of the License, or
00013    (at your option) any later version.
00014 
00015    This program is distributed in the hope that it will be useful,
00016    but WITHOUT ANY WARRANTY; without even the implied warranty of
00017    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018    GNU General Public License for more details.
00019 
00020    You should have received a copy of the GNU General Public License
00021    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
00022 
00023 #ifndef DICTIONARY_H
00024 #define DICTIONARY_H
00025 
00026 #include "symfile.h"
00027 
00028 /* An opaque type for dictionaries; only dictionary.c should know
00029    about its innards.  */
00030 
00031 struct dictionary;
00032 
00033 /* Other types needed for declarations.  */
00034 
00035 struct symbol;
00036 struct obstack;
00037 struct pending;
00038 
00039 
00040 /* The creation functions for various implementations of
00041    dictionaries.  */
00042 
00043 /* Create a dictionary implemented via a fixed-size hashtable.  All
00044    memory it uses is allocated on OBSTACK; the environment is
00045    initialized from SYMBOL_LIST.  */
00046 
00047 extern struct dictionary *dict_create_hashed (struct obstack *obstack,
00048                                               const struct pending
00049                                               *symbol_list);
00050 
00051 /* Create a dictionary implemented via a hashtable that grows as
00052    necessary.  The dictionary is initially empty; to add symbols to
00053    it, call dict_add_symbol().  Call dict_free() when you're done with
00054    it.  */
00055 
00056 extern struct dictionary *dict_create_hashed_expandable (void);
00057 
00058 /* Create a dictionary implemented via a fixed-size array.  All memory
00059    it uses is allocated on OBSTACK; the environment is initialized
00060    from the SYMBOL_LIST.  The symbols are ordered in the same order
00061    that they're found in SYMBOL_LIST.  */
00062 
00063 extern struct dictionary *dict_create_linear (struct obstack *obstack,
00064                                               const struct pending
00065                                               *symbol_list);
00066 
00067 /* Create a dictionary implemented via an array that grows as
00068    necessary.  The dictionary is initially empty; to add symbols to
00069    it, call dict_add_symbol().  Call dict_free() when you're done with
00070    it.  */
00071 
00072 extern struct dictionary *dict_create_linear_expandable (void);
00073 
00074 
00075 /* The functions providing the interface to dictionaries.  Note that
00076    the most common parts of the interface, namely symbol lookup, are
00077    only provided via iterator functions.  */
00078 
00079 /* Free the memory used by a dictionary that's not on an obstack.  (If
00080    any.)  */
00081 
00082 extern void dict_free (struct dictionary *dict);
00083 
00084 /* Add a symbol to an expandable dictionary.  */
00085 
00086 extern void dict_add_symbol (struct dictionary *dict, struct symbol *sym);
00087 
00088 /* Utility to add a list of symbols to a dictionary.  */
00089 
00090 extern void dict_add_pending (struct dictionary *dict,
00091                               const struct pending *symbol_list);
00092 
00093 /* Is the dictionary empty?  */
00094 
00095 extern int dict_empty (struct dictionary *dict);
00096 
00097 /* A type containing data that is used when iterating over all symbols
00098    in a dictionary.  Don't ever look at its innards; this type would
00099    be opaque if we didn't need to be able to allocate it on the
00100    stack.  */
00101 
00102 struct dict_iterator
00103 {
00104   /* The dictionary that this iterator is associated to.  */
00105   const struct dictionary *dict;
00106   /* The next two members are data that is used in a way that depends
00107      on DICT's implementation type.  */
00108   int index;
00109   struct symbol *current;
00110 };
00111 
00112 /* Initialize ITERATOR to point at the first symbol in DICT, and
00113    return that first symbol, or NULL if DICT is empty.  */
00114 
00115 extern struct symbol *dict_iterator_first (const struct dictionary *dict,
00116                                            struct dict_iterator *iterator);
00117 
00118 /* Advance ITERATOR, and return the next symbol, or NULL if there are
00119    no more symbols.  Don't call this if you've previously received
00120    NULL from dict_iterator_first or dict_iterator_next on this
00121    iteration.  */
00122 
00123 extern struct symbol *dict_iterator_next (struct dict_iterator *iterator);
00124 
00125 /* Initialize ITERATOR to point at the first symbol in DICT whose
00126    SYMBOL_SEARCH_NAME is NAME (as tested using strcmp_iw), and return
00127    that first symbol, or NULL if there are no such symbols.  */
00128 
00129 extern struct symbol *dict_iter_name_first (const struct dictionary *dict,
00130                                             const char *name,
00131                                             struct dict_iterator *iterator);
00132 
00133 /* Advance ITERATOR to point at the next symbol in DICT whose
00134    SYMBOL_SEARCH_NAME is NAME (as tested using strcmp_iw), or NULL if
00135    there are no more such symbols.  Don't call this if you've
00136    previously received NULL from dict_iterator_first or
00137    dict_iterator_next on this iteration.  And don't call it unless
00138    ITERATOR was created by a previous call to dict_iter_name_first
00139    with the same NAME.  */
00140 
00141 extern struct symbol *dict_iter_name_next (const char *name,
00142                                            struct dict_iterator *iterator);
00143 
00144 /* Initialize ITERATOR to point at the first symbol in DICT whose
00145    SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (which must use
00146    the same conventions as strcmp_iw and be compatible with any
00147    dictionary hashing function), and return that first symbol, or NULL
00148    if there are no such symbols.  */
00149 
00150 extern struct symbol *dict_iter_match_first (const struct dictionary *dict,
00151                                              const char *name,
00152                                              symbol_compare_ftype *compare,
00153                                              struct dict_iterator *iterator);
00154 
00155 /* Advance ITERATOR to point at the next symbol in DICT whose
00156    SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (see
00157    dict_iter_match_first), or NULL if there are no more such symbols.
00158    Don't call this if you've previously received NULL from 
00159    dict_iterator_match_first or dict_iterator_match_next on this
00160    iteration.  And don't call it unless ITERATOR was created by a
00161    previous call to dict_iter_match_first with the same NAME and COMPARE.  */
00162 
00163 extern struct symbol *dict_iter_match_next (const char *name,
00164                                             symbol_compare_ftype *compare,
00165                                             struct dict_iterator *iterator);
00166 
00167 /* Return some notion of the size of the dictionary: the number of
00168    symbols if we have that, the number of hash buckets otherwise.  */
00169 
00170 extern int dict_size (const struct dictionary *dict);
00171 
00172 /* Macro to loop through all symbols in a dictionary DICT, in no
00173    particular order.  ITER is a struct dict_iterator (NOTE: __not__ a
00174    struct dict_iterator *), and SYM points to the current symbol.
00175 
00176    It's implemented as a single loop, so you can terminate the loop
00177    early by a break if you desire.  */
00178 
00179 #define ALL_DICT_SYMBOLS(dict, iter, sym)                       \
00180         for ((sym) = dict_iterator_first ((dict), &(iter));     \
00181              (sym);                                             \
00182              (sym) = dict_iterator_next (&(iter)))
00183 
00184 #endif /* DICTIONARY_H */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines