mingw/info/gdbint/libgdb.html

   1 <html lang="en">
   2 <head>
   3 <title>GDB Internals</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="GDB Internals">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="libgdb">libgdb</a>,
  13 Next:<a rel="next" accesskey="n" href="Symbol-Handling.html#Symbol%20Handling">Symbol Handling</a>,
  14 Previous:<a rel="previous" accesskey="p" href="User-Interface.html#User%20Interface">User Interface</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">libgdb</h2>
  20
  21 <h3 class="section">libgdb 1.0</h3>
  22
  23    <p><code>libgdb</code> 1.0 was an abortive project of years ago.  The theory was
  24 to provide an API to GDB's functionality.
  25
  26 <h3 class="section">libgdb 2.0</h3>
  27
  28    <p><code>libgdb</code> 2.0 is an ongoing effort to update GDB so that is
  29 better able to support graphical and other environments.
  30
  31    <p>Since <code>libgdb</code> development is on-going, its architecture is still
  32 evolving.  The following components have so far been identified:
  33
  34      <ul>
  35 <li>Observer - <code>gdb-events.h</code>.
  36 <li>Builder - <code>ui-out.h</code>
  37 <li>Event Loop - <code>event-loop.h</code>
  38 <li>Library - <code>gdb.h</code>
  39 </ul>
  40
  41    <p>The model that ties these components together is described below.
  42
  43 <h3 class="section">The <code>libgdb</code> Model</h3>
  44
  45    <p>A client of <code>libgdb</code> interacts with the library in two ways.
  46
  47      <ul>
  48 <li>As an observer (using <code>gdb-events</code>) receiving notifications from
  49 <code>libgdb</code> of any internal state changes (break point changes, run
  50 state, etc).
  51 <li>As a client querying <code>libgdb</code> (using the <code>ui-out</code> builder) to
  52 obtain various status values from GDB.
  53 </ul>
  54
  55    <p>Since <code>libgdb</code> could have multiple clients (e.g. a GUI supporting
  56 the existing GDB CLI), those clients must co-operate when
  57 controlling <code>libgdb</code>.  In particular, a client must ensure that
  58 <code>libgdb</code> is idle (i.e. no other client is using <code>libgdb</code>)
  59 before responding to a <code>gdb-event</code> by making a query.
  60
  61 <h3 class="section">CLI support</h3>
  62
  63    <p>At present GDB's CLI is very much entangled in with the core of
  64 <code>libgdb</code>.  Consequently, a client wishing to include the CLI in
  65 their interface needs to carefully co-ordinate its own and the CLI's
  66 requirements.
  67
  68    <p>It is suggested that the client set <code>libgdb</code> up to be bi-modal
  69 (alternate between CLI and client query modes).  The notes below sketch
  70 out the theory:
  71
  72      <ul>
  73 <li>The client registers itself as an observer of <code>libgdb</code>.
  74 <li>The client create and install <code>cli-out</code> builder using its own
  75 versions of the <code>ui-file</code> <code>gdb_stderr</code>, <code>gdb_stdtarg</code> and
  76 <code>gdb_stdout</code> streams.
  77 <li>The client creates a separate custom <code>ui-out</code> builder that is only
  78 used while making direct queries to <code>libgdb</code>.
  79 </ul>
  80
  81    <p>When the client receives input intended for the CLI, it simply passes it
  82 along.  Since the <code>cli-out</code> builder is installed by default, all
  83 the CLI output in response to that command is routed (pronounced rooted)
  84 through to the client controlled <code>gdb_stdout</code> et. al. streams.
  85 At the same time, the client is kept abreast of internal changes by
  86 virtue of being a <code>libgdb</code> observer.
  87
  88    <p>The only restriction on the client is that it must wait until
  89 <code>libgdb</code> becomes idle before initiating any queries (using the
  90 client's custom builder).
  91
  92 <h3 class="section"><code>libgdb</code> components</h3>
  93
  94 <h4 class="subheading">Observer - <code>gdb-events.h</code></h4>
  95
  96    <p><code>gdb-events</code> provides the client with a very raw mechanism that can
  97 be used to implement an observer.  At present it only allows for one
  98 observer and that observer must, internally, handle the need to delay
  99 the processing of any event notifications until after <code>libgdb</code> has
 100 finished the current command.
 101
 102 <h4 class="subheading">Builder - <code>ui-out.h</code></h4>
 103
 104    <p><code>ui-out</code> provides the infrastructure necessary for a client to
 105 create a builder.  That builder is then passed down to <code>libgdb</code>
 106 when doing any queries.
 107
 108 <h4 class="subheading">Event Loop - <code>event-loop.h</code></h4>
 109
 110    <p><code>event-loop</code>, currently non-re-entrant, provides a simple event
 111 loop.  A client would need to either plug its self into this loop or,
 112 implement a new event-loop that GDB would use.
 113
 114    <p>The event-loop will eventually be made re-entrant.  This is so that
 115 {No value for `GDB'} can better handle the problem of some commands blocking
 116 instead of returning.
 117
 118 <h4 class="subheading">Library - <code>gdb.h</code></h4>
 119
 120    <p><code>libgdb</code> is the most obvious component of this system.  It provides
 121 the query interface.  Each function is parameterized by a <code>ui-out</code>
 122 builder.  The result of the query is constructed using that builder
 123 before the query function returns.
 124
 125    </body></html>
 126