[SCM] archer-tromey-multi-inferior: add comments to itset

[SCM] archer-tromey-multi-inferior: add comments to itset

[tromey]

The branch, archer-tromey-multi-inferior has been updated
       via  c49bae564edecb93ef9f0c031f6f9b94fea66efa (commit)
      from  ce1b52caff5c396ba1ac42d3b20788f27ee3f9ac (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email.

- Log -----------------------------------------------------------------
commit c49bae564edecb93ef9f0c031f6f9b94fea66efa
Author: Tom Tromey <tromey@redhat.com>
Date:   Tue Sep 7 16:40:39 2010 -0600

    add comments to itset

-----------------------------------------------------------------------

Summary of changes:
 gdb/itset.c |  105 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 gdb/itset.h |   19 +++++++++--
 2 files changed, 119 insertions(+), 5 deletions(-)

First 500 lines of diff:
diff --git a/gdb/itset.c b/gdb/itset.c
index f70e256..4b00d30 100644
--- a/gdb/itset.c
+++ b/gdb/itset.c
@@ -26,14 +26,30 @@
 
 #include <ctype.h>
 
+
+/* Forward declaration of the base class.  */
+
 struct itset_base;
 
+/* An element of an I/T set is a class with some virtual methods,
+   defined here.  */
+
 struct itset_vtable
 {
-  int (*contains_inferior) (struct itset_base *, struct inferior *);
+  /* Return true if the element contains the inferior.  The element
+     and the inferior are passed as arguments.  */
+
+  int (*contains_inferior) (struct itset_base *elt, struct inferior *inf);
+
+  /* Destroy the contents of this element.  If the element does not
+     require any special cleanup, this can be NULL.  This should not
+     free the element itself; that is done by the caller.  */
+
   void (*destroy) (struct itset_base *);
 };
 
+/* The base class of all I/T set elements.  */
+
 struct itset_base
 {
   const struct itset_vtable *vtable;
@@ -44,12 +60,18 @@ DEF_VEC_P (itset_base_ptr);
 
 struct itset
 {
+  /* The original specification of the set.  */
   const char *spec;
+
+  /* The elements making up the set.  */
   VEC (itset_base_ptr) *elements;
 };
 
 \f
 
+/* A helper function that returns true if the inferior INF is
+   contained by the set ELEMENTS.  */
+
 static int
 set_contains_inferior (VEC (itset_base_ptr) *elements, struct inferior *inf)
 {
@@ -65,6 +87,9 @@ set_contains_inferior (VEC (itset_base_ptr) *elements, struct inferior *inf)
   return 0;
 }
 
+/* A helper function to destroy all the elements in the set ELEMENTS.
+   This also destroys ELEMENTS itself.  */
+
 static void
 set_free (VEC (itset_base_ptr) *elements)
 {
@@ -83,12 +108,19 @@ set_free (VEC (itset_base_ptr) *elements)
 
 \f
 
+/* An I/T set element representing all inferiors using a certain
+   executable.  */
+
 struct itset_exec
 {
   struct itset_base base;
+
+  /* The name of the executable.  */
   const char *name;
 };
 
+/* Implementation of `contains_inferior' method.  */
+
 static int
 exec_contains_inferior (struct itset_base *base, struct inferior *inf)
 {
@@ -98,6 +130,8 @@ exec_contains_inferior (struct itset_base *base, struct inferior *inf)
   return strcmp (exec->name, bfd_get_filename (inf->pspace->ebfd)) == 0;
 }
 
+/* Implementation of `destroy' method.  */
+
 static void
 exec_destroy (struct itset_base *base)
 {
@@ -112,6 +146,8 @@ static const struct itset_vtable exec_vtable =
   exec_destroy
 };
 
+/* Create a new `exec' I/T set element.  */
+
 static struct itset_base *
 create_exec_itset (const char *arg)
 {
@@ -126,14 +162,26 @@ create_exec_itset (const char *arg)
 
 \f
 
+/* The value representing any inferior or thread.  */
+
+#define WILDCARD -1
+
+/* An I/T set element representing a range of inferiors.  */
+
 struct itset_range
 {
   struct itset_base base;
+
+  /* The first and last inferiors in this range.  If INF_FIRST is
+     WILDCARD, then INF_LAST is unused.  */
   int inf_first, inf_last;
+
+  /* The thread number used by this range.  If WILDCARD, then this
+     matches any thread.  */
   int thread;
 };
 
-#define WILDCARD -1
+/* Implementation of `contains_inferior' method.  */
 
 static int
 range_contains_inferior (struct itset_base *base, struct inferior *inf)
@@ -152,6 +200,8 @@ static const struct itset_vtable range_vtable =
   NULL
 };
 
+/* Create a new `range' I/T set element.  */
+
 static struct itset_base *
 create_range_itset (int inf_first, int inf_last, int thread)
 {
@@ -168,6 +218,8 @@ create_range_itset (int inf_first, int inf_last, int thread)
 
 \f
 
+/* Implementation of `contains_inferior' method.  */
+
 static int
 current_contains_inferior (struct itset_base *base, struct inferior *inf)
 {
@@ -180,6 +232,9 @@ static const struct itset_vtable current_vtable =
   NULL
 };
 
+/* Create a new I/T set element representing just the current
+   inferior.  */
+
 static struct itset_base *
 create_current_itset (void)
 {
@@ -193,18 +248,26 @@ create_current_itset (void)
 
 \f
 
+/* An I/T set element representing a static list of inferiors.  */
+
 struct itset_static
 {
   struct itset_base base;
+
+  /* The inferiors.  */
   VEC (int) *elements;
 };
 
+/* Helper function to compare two ints.  */
+
 static int
 static_lessthan (const int a, const int b)
 {
   return b < a;
 }
 
+/* Implementation of `contains_inferior' method.  */
+
 static int
 static_contains_inferior (struct itset_base *base, struct inferior *inf)
 {
@@ -218,6 +281,8 @@ static_contains_inferior (struct itset_base *base, struct inferior *inf)
   return 0;
 }
 
+/* Implementation of `destroy' method.  */
+
 static void
 static_free (struct itset_base *base)
 {
@@ -232,12 +297,22 @@ static const struct itset_vtable static_vtable =
   static_free
 };
 
+/* Helper struct used to pass data through iterate_over_inferiors.  */
+
 struct iter_data
 {
+  /* The I/T set we are constructing.  */
+
   struct itset_static *st;
+
+  /* The elements of the original (dynamic) I/T set.  */
+
   VEC (itset_base_ptr) *elements;
 };
 
+/* A callback for iterate_over_inferiors that adds an inferior to the
+   result set, if it is in the source set.  */
+
 static int
 check_one_inferior (struct inferior *inf, void *datum)
 {
@@ -250,6 +325,8 @@ check_one_inferior (struct inferior *inf, void *datum)
   return 0;
 }
 
+/* Create a new static I/T set from the list of elements.  */
+
 static struct itset_base *
 create_static_itset (VEC (itset_base_ptr) *elements)
 {
@@ -278,6 +355,9 @@ create_static_itset (VEC (itset_base_ptr) *elements)
 
 \f
 
+/* Helper function to skip whitespace.  Returns an updated pointer
+   into the text.  */
+
 static const char *
 skip_whitespace (const char *text)
 {
@@ -286,6 +366,12 @@ skip_whitespace (const char *text)
   return text;
 }
 
+/* Parse an I/T set range.  A range has the form F[:L][.T], where F is
+   the starting inferior, L is the ending inferior, and T is the
+   thread.  Updates RESULT with the new I/T set elements, and returns
+   an updated pointer into the spec.  Throws an exception on
+   error.  */
+
 static const char *
 parse_range (struct itset *result, const char *text)
 {
@@ -325,6 +411,11 @@ parse_range (struct itset *result, const char *text)
   return text;
 }
 
+/* Parse a named I/T set.  Currently the only named sets which are
+   recognized are `exec (NAME)', and `current'.  Updates RESULT with
+   the new I/T set elements, and returns an updated pointer into the
+   spec.  Throws an exception on error.  */
+
 static const char *
 parse_named (struct itset *result, const char *text)
 {
@@ -368,12 +459,17 @@ parse_named (struct itset *result, const char *text)
   return text;
 }
 
+/* A cleanup function that calls itset_free.  */
+
 static void
 itset_cleanup (void *d)
 {
   itset_free (d);
 }
 
+/* Parse an I/T set specification and return a new I/T set.  Throws an
+   exception on error.  */
+
 struct itset *
 itset_create (const char *spec)
 {
@@ -432,15 +528,20 @@ itset_create (const char *spec)
   return result;
 }
 
+/* Return 1 if SET contains INF, 0 otherwise.  */
+
 int
 itset_contains_inferior (struct itset *set, struct inferior *inf)
 {
   return set_contains_inferior (set->elements, inf);
 }
 
+/* Destroy SET.  */
+
 void
 itset_free (struct itset *set)
 {
   set_free (set->elements);
+  xfree ((char *) set->spec);
   xfree (set);
 }
diff --git a/gdb/itset.h b/gdb/itset.h
index 2c85827..dfd283b 100644
--- a/gdb/itset.h
+++ b/gdb/itset.h
@@ -19,13 +19,26 @@
 #ifndef ITSET_H
 #define ITSET_H
 
-struct itset;
 struct inferior;
 
+/* This is an opaque type representing an I/T set.  An I/T set is
+   simply a set of inferiors and/or threads.  A set may be dynamic
+   (the members are enumerated at the time of use) or static (the
+   members are enumerated at the time of construction); but this
+   distinction is hidden from the callers.  */
+
+struct itset;
+
+/* Create a new I/T set from a user specification.  The valid forms of
+   a specification are documented in the manual.  */
+
 struct itset *itset_create (const char *spec);
 
-int itset_contains_inferior (struct itset *, struct inferior *);
+/* Return true if the inferior is contained in the I/T set.  */
+int itset_contains_inferior (struct itset *itset, struct inferior *inf);
+
+/* Free the I/T set.  */
 
-void itset_free (struct itset *);
+void itset_free (struct itset *itset);
 
 #endif /* ITSET_H */


hooks/post-receive
--
Repository for Project Archer.