event_location -> location_spec

Currently, GDB internally uses the term "location" for both the
location specification the user input (linespec, explicit location, or
an address location), and for actual resolved locations, like the
breakpoint locations, or the result of decoding a location spec to
SaLs.  This is expecially confusing in the breakpoints module, as
struct breakpoint has these two fields:

  breakpoint::location;
  breakpoint::loc;

"location" is the location spec, and "loc" is the resolved locations.

And then, we have a method called "locations()", which returns the
resolved locations as range...

The location spec type is presently called event_location:

  /* Location we used to set the breakpoint.  */
  event_location_up location;

and it is described like this:

  /* The base class for all an event locations used to set a stop event
     in the inferior.  */

  struct event_location
  {

and even that is incorrect...  Location specs are used for finding
actual locations in the program in scenarios that have nothing to do
with stop events.  E.g., "list" works with location specs.

To clean all this confusion up, this patch renames "event_location" to
"location_spec" throughout, and then all the variables that hold a
location spec, they are renamed to include "spec" in their name, like
e.g., "location" -> "locspec".  Similarly, functions that work with
location specs, and currently have just "location" in their name are
renamed to include "spec" in their name too.

Change-Id: I5814124798aa2b2003e79496e78f95c74e5eddca

1 files changed, 167 insertions, 162 deletions

diff --git a/gdb/location.c b/gdb/location.c
index 0459980..14a5aeb 100644
--- a/gdb/location.c
+++ b/gdb/location.c
@@ -1,4 +1,4 @@
-/* Data structures and API for event locations in GDB.
+/* Data structures and API for location specs in GDB.
    Copyright (C) 2013-2022 Free Software Foundation, Inc.
 
    This file is part of GDB.
@@ -32,17 +32,17 @@
 static std::string explicit_location_to_string
      (const struct explicit_location *explicit_loc);
 
-/* The base class for all an event locations used to set a stop event
-   in the inferior.  */
+/* The base class for all location specs used to match actual
+   locations in the inferior.  */
 
-struct event_location
+struct location_spec
 {
-  virtual ~event_location () = default;
+  virtual ~location_spec () = default;
 
   /* Clone this object.  */
-  virtual event_location_up clone () const = 0;
+  virtual location_spec_up clone () const = 0;
 
-  /* Return true if this location is empty, false otherwise.  */
+  /* Return true if this location spec is empty, false otherwise.  */
   virtual bool empty_p () const = 0;
 
   /* Return a string representation of this location.  */
@@ -55,29 +55,29 @@ struct event_location
     return as_string.c_str ();
   }
 
-  DISABLE_COPY_AND_ASSIGN (event_location);
+  DISABLE_COPY_AND_ASSIGN (location_spec);
 
-  /* The type of this breakpoint specification.  */
-  enum event_location_type type;
+  /* The type of this location specification.  */
+  enum location_spec_type type;
 
-  /* Cached string representation of this location.  This is used,
-     e.g., to save stop event locations to file.  */
+  /* Cached string representation of this location spec.  This is
+     used, e.g., to save location specs to file.  */
   mutable std::string as_string;
 
 protected:
 
-  explicit event_location (enum event_location_type t)
+  explicit location_spec (enum location_spec_type t)
     : type (t)
   {
   }
 
-  event_location (enum event_location_type t, std::string &&str)
+  location_spec (enum location_spec_type t, std::string &&str)
     : type (t),
       as_string (std::move (str))
   {
   }
 
-  explicit event_location (const event_location *to_clone)
+  explicit location_spec (const location_spec *to_clone)
     : type (to_clone->type),
       as_string (to_clone->as_string)
   {
@@ -89,16 +89,16 @@ protected:
 };
 
 /* A probe.  */
-struct event_location_probe : public event_location
+struct probe_location_spec : public location_spec
 {
-  explicit event_location_probe (std::string &&probe)
-    : event_location (PROBE_LOCATION, std::move (probe))
+  explicit probe_location_spec (std::string &&probe)
+    : location_spec (PROBE_LOCATION_SPEC, std::move (probe))
   {
   }
 
-  event_location_up clone () const override
+  location_spec_up clone () const override
   {
-    return event_location_up (new event_location_probe (this));
+    return location_spec_up (new probe_location_spec (this));
   }
 
   bool empty_p () const override
@@ -108,8 +108,8 @@ struct event_location_probe : public event_location
 
 protected:
 
-  explicit event_location_probe (const event_location_probe *to_clone)
-    : event_location (to_clone)
+  explicit probe_location_spec (const probe_location_spec *to_clone)
+    : location_spec (to_clone)
   {
   }
 
@@ -120,11 +120,11 @@ protected:
 };
 
 /* A "normal" linespec.  */
-struct event_location_linespec : public event_location
+struct linespec_location_spec : public location_spec
 {
-  event_location_linespec (const char **linespec,
-			   symbol_name_match_type match_type)
-    : event_location (LINESPEC_LOCATION)
+  linespec_location_spec (const char **linespec,
+			  symbol_name_match_type match_type)
+    : location_spec (LINESPEC_LOCATION_SPEC)
   {
     linespec_location.match_type = match_type;
     if (*linespec != NULL)
@@ -144,14 +144,14 @@ struct event_location_linespec : public event_location
       }
   }
 
-  ~event_location_linespec ()
+  ~linespec_location_spec ()
   {
     xfree (linespec_location.spec_string);
   }
 
-  event_location_up clone () const override
+  location_spec_up clone () const override
   {
-    return event_location_up (new event_location_linespec (this));
+    return location_spec_up (new linespec_location_spec (this));
   }
 
   bool empty_p () const override
@@ -163,8 +163,8 @@ struct event_location_linespec : public event_location
 
 protected:
 
-  explicit event_location_linespec (const event_location_linespec *to_clone)
-    : event_location (to_clone),
+  explicit linespec_location_spec (const linespec_location_spec *to_clone)
+    : location_spec (to_clone),
       linespec_location (to_clone->linespec_location)
   {
     if (linespec_location.spec_string != nullptr)
@@ -186,20 +186,20 @@ protected:
 };
 
 /* An address in the inferior.  */
-struct event_location_address : public event_location
+struct address_location_spec : public location_spec
 {
-  event_location_address (CORE_ADDR addr, const char *addr_string,
-			  int addr_string_len)
-    : event_location (ADDRESS_LOCATION),
+  address_location_spec (CORE_ADDR addr, const char *addr_string,
+			 int addr_string_len)
+    : location_spec (ADDRESS_LOCATION_SPEC),
       address (addr)
   {
     if (addr_string != nullptr)
       as_string = std::string (addr_string, addr_string_len);
   }
 
-  event_location_up clone () const override
+  location_spec_up clone () const override
   {
-    return event_location_up (new event_location_address (this));
+    return location_spec_up (new address_location_spec (this));
   }
 
   bool empty_p () const override
@@ -211,8 +211,8 @@ struct event_location_address : public event_location
 
 protected:
 
-  event_location_address (const event_location_address *to_clone)
-    : event_location (to_clone),
+  address_location_spec (const address_location_spec *to_clone)
+    : location_spec (to_clone),
       address (to_clone->address)
   {
   }
@@ -224,25 +224,25 @@ protected:
   }
 };
 
-/* An explicit location.  */
-struct event_location_explicit : public event_location
+/* An explicit location spec.  */
+struct explicit_location_spec : public location_spec
 {
-  explicit event_location_explicit (const struct explicit_location *loc)
-    : event_location (EXPLICIT_LOCATION)
+  explicit explicit_location_spec (const struct explicit_location *loc)
+    : location_spec (EXPLICIT_LOCATION_SPEC)
   {
     copy_loc (loc);
   }
 
-  ~event_location_explicit ()
+  ~explicit_location_spec ()
   {
     xfree (explicit_loc.source_filename);
     xfree (explicit_loc.function_name);
     xfree (explicit_loc.label_name);
   }
 
-  event_location_up clone () const override
+  location_spec_up clone () const override
   {
-    return event_location_up (new event_location_explicit (this));
+    return location_spec_up (new explicit_location_spec (this));
   }
 
   bool empty_p () const override
@@ -257,8 +257,8 @@ struct event_location_explicit : public event_location
 
 protected:
 
-  explicit event_location_explicit (const event_location_explicit *to_clone)
-    : event_location (to_clone)
+  explicit explicit_location_spec (const explicit_location_spec *to_clone)
+    : location_spec (to_clone)
   {
     copy_loc (&to_clone->explicit_loc);
   }
@@ -289,10 +289,10 @@ private:
 
 /* See description in location.h.  */
 
-enum event_location_type
-event_location_type (const struct event_location *location)
+enum location_spec_type
+location_spec_type (const location_spec *locspec)
 {
-  return location->type;
+  return locspec->type;
 }
 
 /* See description in location.h.  */
@@ -307,99 +307,99 @@ initialize_explicit_location (struct explicit_location *explicit_loc)
 
 /* See description in location.h.  */
 
-event_location_up
-new_linespec_location (const char **linespec,
-		       symbol_name_match_type match_type)
+location_spec_up
+new_linespec_location_spec (const char **linespec,
+			    symbol_name_match_type match_type)
 {
-  return event_location_up (new event_location_linespec (linespec,
-							 match_type));
+  return location_spec_up (new linespec_location_spec (linespec,
+						       match_type));
 }
 
 /* See description in location.h.  */
 
 const linespec_location *
-get_linespec_location (const struct event_location *location)
+get_linespec_location (const location_spec *locspec)
 {
-  gdb_assert (location->type == LINESPEC_LOCATION);
-  return &((event_location_linespec *) location)->linespec_location;
+  gdb_assert (locspec->type == LINESPEC_LOCATION_SPEC);
+  return &((linespec_location_spec *) locspec)->linespec_location;
 }
 
 /* See description in location.h.  */
 
-event_location_up
-new_address_location (CORE_ADDR addr, const char *addr_string,
-		      int addr_string_len)
+location_spec_up
+new_address_location_spec (CORE_ADDR addr, const char *addr_string,
+			   int addr_string_len)
 {
-  return event_location_up (new event_location_address (addr, addr_string,
-							addr_string_len));
+  return location_spec_up (new address_location_spec (addr, addr_string,
+						      addr_string_len));
 }
 
 /* See description in location.h.  */
 
 CORE_ADDR
-get_address_location (const struct event_location *location)
+get_address_location (const location_spec *locspec)
 {
-  gdb_assert (location->type == ADDRESS_LOCATION);
-  return ((event_location_address *) location)->address;
+  gdb_assert (locspec->type == ADDRESS_LOCATION_SPEC);
+  return ((address_location_spec *) locspec)->address;
 }
 
 /* See description in location.h.  */
 
 const char *
-get_address_string_location (const struct event_location *location)
+get_address_string_location (const location_spec *locspec)
 {
-  gdb_assert (location->type == ADDRESS_LOCATION);
-  return location->to_string ();
+  gdb_assert (locspec->type == ADDRESS_LOCATION_SPEC);
+  return locspec->to_string ();
 }
 
 /* See description in location.h.  */
 
-event_location_up
-new_probe_location (std::string &&probe)
+location_spec_up
+new_probe_location_spec (std::string &&probe)
 {
-  return event_location_up (new event_location_probe (std::move (probe)));
+  return location_spec_up (new probe_location_spec (std::move (probe)));
 }
 
 /* See description in location.h.  */
 
 const char *
-get_probe_location (const struct event_location *location)
+get_probe_location_spec_string (const location_spec *locspec)
 {
-  gdb_assert (location->type == PROBE_LOCATION);
-  return location->to_string ();
+  gdb_assert (locspec->type == PROBE_LOCATION_SPEC);
+  return locspec->to_string ();
 }
 
 /* See description in location.h.  */
 
-event_location_up
-new_explicit_location (const struct explicit_location *explicit_loc)
+location_spec_up
+new_explicit_location_spec (const explicit_location *explicit_loc)
 {
-  return event_location_up (new event_location_explicit (explicit_loc));
+  return location_spec_up (new explicit_location_spec (explicit_loc));
 }
 
 /* See description in location.h.  */
 
 struct explicit_location *
-get_explicit_location (struct event_location *location)
+get_explicit_location (location_spec *locspec)
 {
-  gdb_assert (location->type == EXPLICIT_LOCATION);
-  return &((event_location_explicit *) location)->explicit_loc;
+  gdb_assert (locspec->type == EXPLICIT_LOCATION_SPEC);
+  return &((explicit_location_spec *) locspec)->explicit_loc;
 }
 
 /* See description in location.h.  */
 
 const struct explicit_location *
-get_explicit_location_const (const struct event_location *location)
+get_explicit_location_const (const location_spec *locspec)
 {
-  gdb_assert (location->type == EXPLICIT_LOCATION);
-  return &((event_location_explicit *) location)->explicit_loc;
+  gdb_assert (locspec->type == EXPLICIT_LOCATION_SPEC);
+  return &((explicit_location_spec *) locspec)->explicit_loc;
 }
 
-/* This convenience function returns a malloc'd string which
-   represents the location in EXPLICIT_LOC.
+/* Return a string representation of the explicit location spec in
+   EXPLICIT_LOCSPEC.
 
-   AS_LINESPEC is true if this string should be a linespec.
-   Otherwise it will be output in explicit form.  */
+   AS_LINESPEC is true if this string should be a linespec.  Otherwise
+   it will be output in explicit form.  */
 
 static std::string
 explicit_to_string_internal (bool as_linespec,
@@ -473,24 +473,24 @@ explicit_location_to_linespec (const struct explicit_location *explicit_loc)
 
 /* See description in location.h.  */
 
-event_location_up
-copy_event_location (const struct event_location *src)
+location_spec_up
+copy_location_spec (const location_spec *src)
 {
   return src->clone ();
 }
 
 void
-event_location_deleter::operator() (event_location *location) const
+location_spec_deleter::operator() (location_spec *locspec) const
 {
-  delete location;
+  delete locspec;
 }
 
 /* See description in location.h.  */
 
 const char *
-event_location_to_string (struct event_location *location)
+location_spec_to_string (struct location_spec *locspec)
 {
-  return location->to_string ();
+  return locspec->to_string ();
 }
 
 /* Find an instance of the quote character C in the string S that is
@@ -523,14 +523,14 @@ find_end_quote (const char *s, char end_quote_char)
   return 0;
 }
 
-/* A lexer for explicit locations.  This function will advance INP
-   past any strings that it lexes.  Returns a malloc'd copy of the
+/* A lexer for explicit location specs.  This function will advance
+   INP past any strings that it lexes.  Returns a malloc'd copy of the
    lexed string or NULL if no lexing was done.  */
 
 static gdb::unique_xmalloc_ptr<char>
-explicit_location_lex_one (const char **inp,
-			   const struct language_defn *language,
-			   explicit_completion_info *completion_info)
+explicit_location_spec_lex_one (const char **inp,
+				const struct language_defn *language,
+				explicit_completion_info *completion_info)
 {
   const char *start = *inp;
 
@@ -630,7 +630,7 @@ is_cp_operator (const char *start, const char *comma)
 }
 
 /* When scanning the input string looking for the next explicit
-   location option/delimiter, we jump to the next option by looking
+   location spec option/delimiter, we jump to the next option by looking
    for ",", and "-".  Such a character can also appear in C++ symbols
    like "operator," and "operator-".  So when we find such a
    character, we call this function to check if we found such a
@@ -673,15 +673,16 @@ first_of (const char *first, const char *new_tok)
     return first;
 }
 
-/* A lexer for functions in explicit locations.  This function will
+/* A lexer for functions in explicit location specs.  This function will
    advance INP past a function until the next option, or until end of
    string.  Returns a malloc'd copy of the lexed string or NULL if no
    lexing was done.  */
 
 static gdb::unique_xmalloc_ptr<char>
-explicit_location_lex_one_function (const char **inp,
-				    const struct language_defn *language,
-				    explicit_completion_info *completion_info)
+explicit_location_spec_lex_one_function
+  (const char **inp,
+   const struct language_defn *language,
+   explicit_completion_info *completion_info)
 {
   const char *start = *inp;
 
@@ -771,10 +772,10 @@ explicit_location_lex_one_function (const char **inp,
 
 /* See description in location.h.  */
 
-event_location_up
-string_to_explicit_location (const char **argp,
-			     const struct language_defn *language,
-			     explicit_completion_info *completion_info)
+location_spec_up
+string_to_explicit_location_spec (const char **argp,
+				  const struct language_defn *language,
+				  explicit_completion_info *completion_info)
 {
   /* It is assumed that input beginning with '-' and a non-digit
      character is an explicit location.  "-p" is reserved, though,
@@ -786,8 +787,8 @@ string_to_explicit_location (const char **argp,
       || ((*argp)[0] == '-' && (*argp)[1] == 'p'))
     return NULL;
 
-  std::unique_ptr<event_location_explicit> location
-    (new event_location_explicit ((const explicit_location *) nullptr));
+  std::unique_ptr<explicit_location_spec> locspec
+    (new explicit_location_spec ((const explicit_location *) nullptr));
 
   /* Process option/argument pairs.  dprintf_command
      requires that processing stop on ','.  */
@@ -817,7 +818,7 @@ string_to_explicit_location (const char **argp,
 
       /* Get the option string.  */
       gdb::unique_xmalloc_ptr<char> opt
-	= explicit_location_lex_one (argp, language, NULL);
+	= explicit_location_spec_lex_one (argp, language, NULL);
 
       /* Use the length of the option to allow abbreviations.  */
       len = strlen (opt.get ());
@@ -845,7 +846,7 @@ string_to_explicit_location (const char **argp,
 	      /* We do this here because the set of options that take
 		 arguments matches the set of explicit location
 		 options.  */
-	      completion_info->saw_explicit_location_option = true;
+	      completion_info->saw_explicit_location_spec_option = true;
 	    }
 	  oarg = std::move (arg);
 	  have_oarg = oarg != NULL;
@@ -854,36 +855,37 @@ string_to_explicit_location (const char **argp,
 
       if (strncmp (opt.get (), "-source", len) == 0)
 	{
-	  set_oarg (explicit_location_lex_one (argp, language,
-					       completion_info));
-	  location->explicit_loc.source_filename = oarg.release ();
+	  set_oarg (explicit_location_spec_lex_one (argp, language,
+						    completion_info));
+	  locspec->explicit_loc.source_filename = oarg.release ();
 	}
       else if (strncmp (opt.get (), "-function", len) == 0)
 	{
-	  set_oarg (explicit_location_lex_one_function (argp, language,
-							completion_info));
-	  location->explicit_loc.function_name = oarg.release ();
+	  set_oarg (explicit_location_spec_lex_one_function (argp, language,
+							     completion_info));
+	  locspec->explicit_loc.function_name = oarg.release ();
 	}
       else if (strncmp (opt.get (), "-qualified", len) == 0)
 	{
-	  location->explicit_loc.func_name_match_type
+	  locspec->explicit_loc.func_name_match_type
 	    = symbol_name_match_type::FULL;
 	}
       else if (strncmp (opt.get (), "-line", len) == 0)
 	{
-	  set_oarg (explicit_location_lex_one (argp, language, NULL));
+	  set_oarg (explicit_location_spec_lex_one (argp, language, NULL));
 	  *argp = skip_spaces (*argp);
 	  if (have_oarg)
 	    {
-	      location->explicit_loc.line_offset
+	      locspec->explicit_loc.line_offset
 		= linespec_parse_line_offset (oarg.get ());
 	      continue;
 	    }
 	}
       else if (strncmp (opt.get (), "-label", len) == 0)
 	{
-	  set_oarg (explicit_location_lex_one (argp, language, completion_info));
-	  location->explicit_loc.label_name = oarg.release ();
+	  set_oarg (explicit_location_spec_lex_one (argp, language,
+						    completion_info));
+	  locspec->explicit_loc.label_name = oarg.release ();
 	}
       /* Only emit an "invalid argument" error for options
 	 that look like option strings.  */
@@ -913,39 +915,39 @@ string_to_explicit_location (const char **argp,
 
   /* One special error check:  If a source filename was given
      without offset, function, or label, issue an error.  */
-  if (location->explicit_loc.source_filename != NULL
-      && location->explicit_loc.function_name == NULL
-      && location->explicit_loc.label_name == NULL
-      && (location->explicit_loc.line_offset.sign == LINE_OFFSET_UNKNOWN)
+  if (locspec->explicit_loc.source_filename != NULL
+      && locspec->explicit_loc.function_name == NULL
+      && locspec->explicit_loc.label_name == NULL
+      && (locspec->explicit_loc.line_offset.sign == LINE_OFFSET_UNKNOWN)
       && completion_info == NULL)
     {
       error (_("Source filename requires function, label, or "
 	       "line offset."));
     }
 
-  return event_location_up (location.release ());
+  return location_spec_up (locspec.release ());
 }
 
 /* See description in location.h.  */
 
-event_location_up
-string_to_event_location_basic (const char **stringp,
-				const struct language_defn *language,
-				symbol_name_match_type match_type)
+location_spec_up
+string_to_location_spec_basic (const char **stringp,
+			       const struct language_defn *language,
+			       symbol_name_match_type match_type)
 {
-  event_location_up location;
+  location_spec_up locspec;
   const char *cs;
 
   /* Try the input as a probe spec.  */
   cs = *stringp;
   if (cs != NULL && probe_linespec_to_static_ops (&cs) != NULL)
     {
-      location = new_probe_location (*stringp);
+      locspec = new_probe_location_spec (*stringp);
       *stringp += strlen (*stringp);
     }
   else
     {
-      /* Try an address location.  */
+      /* Try an address location spec.  */
       if (*stringp != NULL && **stringp == '*')
 	{
 	  const char *arg, *orig;
@@ -953,69 +955,72 @@ string_to_event_location_basic (const char **stringp,
 
 	  orig = arg = *stringp;
 	  addr = linespec_expression_to_pc (&arg);
-	  location = new_address_location (addr, orig, arg - orig);
+	  locspec = new_address_location_spec (addr, orig, arg - orig);
 	  *stringp += arg - orig;
 	}
       else
 	{
 	  /* Everything else is a linespec.  */
-	  location = new_linespec_location (stringp, match_type);
+	  locspec = new_linespec_location_spec (stringp, match_type);
 	}
     }
 
-  return location;
+  return locspec;
 }
 
 /* See description in location.h.  */
 
-event_location_up
-string_to_event_location (const char **stringp,
-			  const struct language_defn *language,
-			  symbol_name_match_type match_type)
+location_spec_up
+string_to_location_spec (const char **stringp,
+			 const struct language_defn *language,
+			 symbol_name_match_type match_type)
 {
   const char *arg, *orig;
 
-  /* Try an explicit location.  */
+  /* Try an explicit location spec.  */
   orig = arg = *stringp;
-  event_location_up location = string_to_explicit_location (&arg, language, NULL);
-  if (location != NULL)
+  location_spec_up locspec
+    = string_to_explicit_location_spec (&arg, language, NULL);
+  if (locspec != nullptr)
     {
       /* It was a valid explicit location.  Advance STRINGP to
 	 the end of input.  */
       *stringp += arg - orig;
 
-      /* If the user really specified a location, then we're done.  */
-      if (!event_location_empty_p (location.get ()))
-	return location;
+      /* If the user really specified a location spec, then we're
+	 done.  */
+      if (!location_spec_empty_p (locspec.get ()))
+	return locspec;
 
       /* Otherwise, the user _only_ specified optional flags like
-	 "-qualified", otherwise string_to_explicit_location would
-	 have thrown an error.  Save the flags for "basic" linespec
-	 parsing below and discard the explicit location.  */
-      event_location_explicit *xloc
-	= dynamic_cast<event_location_explicit *> (location.get ());
+	 "-qualified", otherwise string_to_explicit_location_spec
+	 would have thrown an error.  Save the flags for "basic"
+	 linespec parsing below and discard the explicit location
+	 spec.  */
+      explicit_location_spec *xloc
+	= dynamic_cast<explicit_location_spec *> (locspec.get ());
       gdb_assert (xloc != nullptr);
       match_type = xloc->explicit_loc.func_name_match_type;
     }
 
-  /* Everything else is a "basic" linespec, address, or probe
-     location.  */
-  return string_to_event_location_basic (stringp, language, match_type);
+  /* Everything else is a "basic" linespec, address, or probe location
+     spec.  */
+  return string_to_location_spec_basic (stringp, language, match_type);
 }
 
 /* See description in location.h.  */
 
 int
-event_location_empty_p (const struct event_location *location)
+location_spec_empty_p (const location_spec *locspec)
 {
-  return location->empty_p ();
+  return locspec->empty_p ();
 }
 
 /* See description in location.h.  */
 
 void
-set_event_location_string (struct event_location *location,
-			   std::string &&string)
+set_location_spec_string (struct location_spec *locspec,
+			  std::string &&string)
 {
-  location->as_string = std::move (string);
+  locspec->as_string = std::move (string);
 }