gdb/dictionary.h - gdb

Data types defined

Macros defined

Source code

  1. /* Routines for name->symbol lookups in GDB.

  3.    Copyright (C) 2003-2015 Free Software Foundation, Inc.

  5.    Contributed by David Carlton <carlton@bactrian.org> and by Kealia,
  6.    Inc.

  8.    This file is part of GDB.

  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.

  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.

  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/>.  */

  23. #ifndef DICTIONARY_H
  24. ‌#define DICTIONARY_H

  26. #include "symfile.h"

  28. /* An opaque type for dictionaries; only dictionary.c should know
  29.    about its innards.  */

  31. struct dictionary;

  33. /* Other types needed for declarations.  */

  35. struct symbol;
  36. struct obstack;
  37. struct pending;


  40. /* The creation functions for various implementations of
  41.    dictionaries.  */

  43. /* Create a dictionary implemented via a fixed-size hashtable.  All
  44.    memory it uses is allocated on OBSTACK; the environment is
  45.    initialized from SYMBOL_LIST.  */

  47. extern struct dictionary *dict_create_hashed (struct obstack *obstack,
  48.                                               const struct pending
  49.                                               *symbol_list);

  51. /* Create a dictionary implemented via a hashtable that grows as
  52.    necessary.  The dictionary is initially empty; to add symbols to
  53.    it, call dict_add_symbol().  Call dict_free() when you're done with
  54.    it.  */

  56. extern struct dictionary *dict_create_hashed_expandable (void);

  58. /* Create a dictionary implemented via a fixed-size array.  All memory
  59.    it uses is allocated on OBSTACK; the environment is initialized
  60.    from the SYMBOL_LIST.  The symbols are ordered in the same order
  61.    that they're found in SYMBOL_LIST.  */

  63. extern struct dictionary *dict_create_linear (struct obstack *obstack,
  64.                                               const struct pending
  65.                                               *symbol_list);

  67. /* Create a dictionary implemented via an array that grows as
  68.    necessary.  The dictionary is initially empty; to add symbols to
  69.    it, call dict_add_symbol().  Call dict_free() when you're done with
  70.    it.  */

  72. extern struct dictionary *dict_create_linear_expandable (void);


  75. /* The functions providing the interface to dictionaries.  Note that
  76.    the most common parts of the interface, namely symbol lookup, are
  77.    only provided via iterator functions.  */

  79. /* Free the memory used by a dictionary that's not on an obstack.  (If
  80.    any.)  */

  82. extern void dict_free (struct dictionary *dict);

  84. /* Add a symbol to an expandable dictionary.  */

  86. extern void dict_add_symbol (struct dictionary *dict, struct symbol *sym);

  88. /* Utility to add a list of symbols to a dictionary.  */

  90. extern void dict_add_pending (struct dictionary *dict,
  91.                               const struct pending *symbol_list);

  93. /* Is the dictionary empty?  */

  95. extern int dict_empty (struct dictionary *dict);

  97. /* A type containing data that is used when iterating over all symbols
  98.    in a dictionary.  Don't ever look at its innards; this type would
  99.    be opaque if we didn't need to be able to allocate it on the
  100.    stack.  */

  102. ‌struct dict_iterator
  103. {
  104.   /* The dictionary that this iterator is associated to.  */
  105.   const struct dictionary *dict;
  106.   /* The next two members are data that is used in a way that depends
  107.      on DICT's implementation type.  */
  108.   int index;
  109.   struct symbol *current;
  110. };

  112. /* Initialize ITERATOR to point at the first symbol in DICT, and
  113.    return that first symbol, or NULL if DICT is empty.  */

  115. extern struct symbol *dict_iterator_first (const struct dictionary *dict,
  116.                                            struct dict_iterator *iterator);

  118. /* Advance ITERATOR, and return the next symbol, or NULL if there are
  119.    no more symbols.  Don't call this if you've previously received
  120.    NULL from dict_iterator_first or dict_iterator_next on this
  121.    iteration.  */

  123. extern struct symbol *dict_iterator_next (struct dict_iterator *iterator);

  125. /* Initialize ITERATOR to point at the first symbol in DICT whose
  126.    SYMBOL_SEARCH_NAME is NAME (as tested using strcmp_iw), and return
  127.    that first symbol, or NULL if there are no such symbols.  */

  129. extern struct symbol *dict_iter_name_first (const struct dictionary *dict,
  130.                                             const char *name,
  131.                                             struct dict_iterator *iterator);

  133. /* Advance ITERATOR to point at the next symbol in DICT whose
  134.    SYMBOL_SEARCH_NAME is NAME (as tested using strcmp_iw), or NULL if
  135.    there are no more such symbols.  Don't call this if you've
  136.    previously received NULL from dict_iterator_first or
  137.    dict_iterator_next on this iteration.  And don't call it unless
  138.    ITERATOR was created by a previous call to dict_iter_name_first
  139.    with the same NAME.  */

  141. extern struct symbol *dict_iter_name_next (const char *name,
  142.                                            struct dict_iterator *iterator);

  144. /* Initialize ITERATOR to point at the first symbol in DICT whose
  145.    SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (which must use
  146.    the same conventions as strcmp_iw and be compatible with any
  147.    dictionary hashing function), and return that first symbol, or NULL
  148.    if there are no such symbols.  */

  150. extern struct symbol *dict_iter_match_first (const struct dictionary *dict,
  151.                                              const char *name,
  152.                                              symbol_compare_ftype *compare,
  153.                                              struct dict_iterator *iterator);

  155. /* Advance ITERATOR to point at the next symbol in DICT whose
  156.    SYMBOL_SEARCH_NAME is NAME, as tested using COMPARE (see
  157.    dict_iter_match_first), or NULL if there are no more such symbols.
  158.    Don't call this if you've previously received NULL from
  159.    dict_iterator_match_first or dict_iterator_match_next on this
  160.    iteration.  And don't call it unless ITERATOR was created by a
  161.    previous call to dict_iter_match_first with the same NAME and COMPARE.  */

  163. extern struct symbol *dict_iter_match_next (const char *name,
  164.                                             symbol_compare_ftype *compare,
  165.                                             struct dict_iterator *iterator);

  167. /* Return some notion of the size of the dictionary: the number of
  168.    symbols if we have that, the number of hash buckets otherwise.  */

  170. extern int dict_size (const struct dictionary *dict);

  172. /* Macro to loop through all symbols in a dictionary DICT, in no
  173.    particular order.  ITER is a struct dict_iterator (NOTE: __not__ a
  174.    struct dict_iterator *), and SYM points to the current symbol.

  176.    It's implemented as a single loop, so you can terminate the loop
  177.    early by a break if you desire.  */

  179. ‌#define ALL_DICT_SYMBOLS(dict, iter, sym)                        \
  180.         for ((sym) = dict_iterator_first ((dict), &(iter));        \
  181.              (sym);                                                \
  182.              (sym) = dict_iterator_next (&(iter)))

  184. #endif /* DICTIONARY_H */