Dwfl Callbacks

[Roland McGrath <roland@redhat.com>]

There are two independent subjects here, so I'll take one at a time in
separate messages.  First, the general issue of dealing with libdwfl callbacks.

I don't know the Frysk code or the Java wrappers in any detail, so I will
just speak to the general case of using the library in C/C++.

It's true that there is no interface to get the Dwfl_Callbacks pointer from
a Dwfl or Dwfl_Module, or the Dwfl from a Dwfl_Module.  These would be
simple to add.  That would make it possible to embed Dwfl_Callbacks in a
larger structure and recover a pointer to your own data from that (e.g. via
C++ multiple inheritance).  But I always figured applications would set the
module userdata to point at a per-module data structure of their own, and
use that to find anything else of theirs in callbacks.

Callbacks get passed void **userdata, and you can get this pointer from
dwfl_module_info on a Dwfl_Module.  This gives the location of a void *
inside the Dwfl_Module that belongs to the application.  The usage model I
expect is that when populating a Dwfl by calling dwfl_report_module (or
things that call it, like dwfl_report_elf, dwfl_report_offline), an
application sets each module's userdata to point to its own data structure
about that module (if it has one, or some other structure it wants).  To do
this after each dwfl_report_module call, you'd call dwfl_module_info to get
the void **.  After reporting, you could do that on Dwfl_Module pointers
you have, or use dwfl_getmodules and get the void ** in each callback along
with the Dwfl_Module *.  When you have the void **, then store there any
void * that floats your boat, or fetch what you stored before.  The void *
field starts out as NULL, and libdwfl never touches it or looks at it, only
passes its address to you.

As a reminder, the general model of libdwfl is that a reporting pass from
dwfl_report_begin (or dwfl_report_begin_add) to dwfl_report_end sets up the
current set of modules in the address space one Dwfl object describes.
The general-purpose library code itself assigns no meaning to the name of
a module at all.  The only meaning of the name is that a module is
identified by the tuple (name, start-address, end-address), which are the
arguments to dwfl_report_module.  When it's called with all three of those
matching an existing module, that means that module is still there and you
get the same pointer back.  There can be multiple modules with the same
name and different addresses.  The names are up to you and your callback
functions.  You could use the names to drive the work of the callbacks.
dwfl_linux_proc_find_elf is a kludgey callback for simple users; it uses
the module names as meaningful.  But complex applications like Frysk
should have their own data structure associated with each module and use
that to drive their callbacks.

What I would think is the natural binding of this interface to an OO
language is as follows.  The per-module object in the binding (perhaps
called Dwfl_Module, or maybe it's Dwfl::Module) wraps the C Dwfl_Module *,
has various methods corresponding to dwfl_module_* functions, and is
subclassable by users.  When a per-module object is created, it sets the C
Dwfl_Module's userdata to point to that language-binding object.  The
binding glue for the various callback functions taking arguments
(Dwfl_Module *mod, void **userdata, const char *modname, Dwarf_Addr base,
...) fetches the binding object from *userdata and passes just
(Dwfl::Module, ...)  with the meaningful arguments in that particular
callback to the language-level callback.  (In the C interface, those four
arguments are always given for convenience of writing callback functions
in C, but the last three are all things you can get from the Dwfl_Module.)
A per-module object is created by the bindings for the reporting calls,
and/or perhaps on demand in other callback bindings that get arguments
(mod, userdata, ...) with *userdata == NULL.

At the level of Java, you would subclass Dwfl::Module with a frysk.module
or whatnot that defines an interface of methods you call from your
find_elf callback wrapper.  Then you have subclasses of that implementing
those differently for different kinds of modules, like on-disk modules and
memory-only (vDSO) modules.


Thanks,
Roland