Re: Batons? Was: RFC: C/C++ preprocessor macro support for GDB

[Jim Blandy <jimb at redhat dot com>]

Andrew Cagney <ac131313@cygnus.com> writes:
> Jim, assuming I understand the intent correctly, I'm just wondering
> about the use of the word baton (I've seen it before).

It's a term we coined for Subversion.

Subversion uses pointers to functions a lot --- it helps us preserve
modularity in cases where we have too much data to hold in memory all
at once, and we instead need to provide processing functions that get
one chunk of data at a time.  And in other cases.

Subversion follows the convention that, whenever a function takes a
pointer to a function as an argument, or whenever a data structure
stores a pointer to a function, we also take/store an untyped pointer
which we promise to pass along to that function each time we call it,
along with the other arguments.  Whoever gives us the actual function
pointer also has to give us an appropriate untyped pointer.

This is a pretty specific usage pattern for a void * pointer, so it
made sense to make up a name for it.  Whenever you see a "baton", you
know to ask what function it goes with.

Newly coined terms are pretty annoying.  It's as if the coiner is
inviting you to admire his/her cleverness.  But at last count, the
term "baton" appears ~4200 times in the Subversion sources (~200k
lines of code), so I think it's easy to argue that the Subversion
developers have found it useful in explaining what they're doing.

The GDB macro patch only uses one kind of baton:

+ /* A function for looking up preprocessor macro definitions.  Return
+    the preprocessor definition of NAME in scope according to BATON, or
+    zero if NAME is not defined as a preprocessor macro.
+ 
+    The caller must not free or modify the definition returned.  It is
+    probably unwise for the caller to hold pointers to it for very
+    long; it probably lives in some objfile's obstacks.  */
+ typedef struct macro_definition *(macro_lookup_ftype) (const char *name,
+                                                        void *baton);
+ 
+ 
+ /* Expand any preprocessor macros in SOURCE, and return the expanded
+    text.  Use LOOKUP_FUNC and LOOKUP_FUNC_BATON to find identifiers'
+    preprocessor definitions.  SOURCE is a null-terminated string.  The
+    result is a null-terminated string, allocated using xmalloc; it is
+    the caller's responsibility to free it.  */
+ char *macro_expand (const char *source,
+                     macro_lookup_ftype *lookup_func,
+                     void *lookup_func_baton);

Since this would be the only use of the term "baton" in the entire
source tree, it's not exactly helping people understand things more
there.  In the Subversion code base, things are different, since it's
widely used.

I'm open to suggestions.  If folks think it's too cutesy, I'll change
it to whatever they want.