struct environment

[David Carlton <carlton@math.stanford.edu>]

As I e-mailed a couple of weeks ago, I'd like to work on reworking the
namespace support in GDB.  But, before working on namespaces proper,
there's a fair amount of existing code in GDB that is relevant to this
task that I'd like to clean up.  Specifically, I think that namespace
support will be much saner if all existing symbol lookup mechanisms
are unified into some sort of 'environment' interface.

The existing mechanisms in question are:

1) The members 'hashtable', 'nsyms', and 'sym' of 'struct block'.
2) The global environment: global symbols, partial symbols, minimal
   symbols.
3) The members '{n,}fields' in 'struct type'.

Namespaces are similar in many ways to the global environment, so
taming the global environment code will be very helpful when reworking
namespaces.  And once we handle 'using' declarations, symbol lookups
won't always proceed up a straightforward line of inheritance of
blocks that ends in the global environment, so I suspect that having
blocks, the global environment, and namespaces all be accessible via
the same sort of object will make code simpler.  (Exactly why the
third case above should be handled in the same way is another story,
but I don't want to go into that now.)

So I want to add a type 'struct environment' to GDB.  It will be
completely opaque, with a variety of internal implementations
available (similar to the way that 'struct block' allows you to use
either a hash table or a simple list of symbols) sharing a common
external interface.  I want to start by converting 'struct block' over
to using this, then converting the global environment over to using
this, then (probably) 'struct type', and finally getting namespaces to
work well.

I think I'll soon be ready to start converting over 'struct block',
and I'd like feedback from people about whether or not this is a good
idea, and about what the parts of the interface to 'struct
environment' that are relevant to 'struct block' should look like.
Here are some design issues that arise:

* What constructors/destructors should there be?  buildsym.c will need
  constructors that create environments of a fixed size on an obstack
  that are implemented using either a hashtable or a list.  jv-lang.c
  and mdebugread.c both need constructors for environments allocated
  using xmalloc whose final size isn't known initially; these will
  need destructors, and perhaps some sort of 'finalize' function to
  call once we know everything's been added to the environments in
  question.  (I'll look into those situations more closely soon.)

* There needs to be a way to add symbols to an environment while
  constructing it.  Maybe

    void env_add_symbol(struct environment *, struct symbol *);

* There should be a shallow lookup function, i.e. one that looks up a
  symbol just in one environment, without going up to a parent
  environment.  (The latter will get added in once we get to
  converting over the global environment.)  Maybe

    struct symbol *env_lookup_shallow(struct environment *,
                                      const char *);

* There should probably be iterators that allow one to examine every
  symbol in an environment.  One possibility, to save on memory
  management headaches, would be to allow only one active iterator per
  environment, and have that stored as part of the environment; so we
  would have

    struct symbol *env_lookup_first(struct environment *);
    struct symbol *env_lookup_next(struct environment *);

  (Where these return NULL if we've seen all the symbols in the
  environment.)  I'll have to double-check to make sure that existing
  use of iteration over symbols blocks is compatible with this, but
  I'm almost positive it is.

* It's vaguely possible that some code might need to count the number
  of symbols in an environment, but I don't think so; presumably
  that's only used by iterators or by code that could be moved to the
  inside of struct environment.

* When scanning GDB for uses of 'struct block', I noticed that some
  code wants to sort symbols in the block.  I'll have to look at where
  and why that's happening, but I don't think it's anything serious.
  (When it's necessary, it can presumably be added to a 'finalize'
  function as in the discussion of constructors above.)

I think that's about it.

That describes how I would like things to look once I've switched
'struct block' over to using a 'struct environment' member (replacing
its current members 'hashtable', 'nsyms', and 'sym').  And presumably
most or all of this portion of the interface will remain once the
global environment has been converted over, though of course the
interface will grow in order to handle the global environment.

The question remains of how to get from here to there.  I'm pretty
sure that I can convert 'struct block' over to using environments in
an incremental fashion.  Describing that process will take a fair
amount of time, though, so I'll send it in a separate e-mail, probably
some time tomorrow but maybe Monday.

David Carlton
carlton@math.stanford.edu