| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Exporting a C API</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="index.html" title="GObject Reference Manual"> |
| <link rel="up" href="chapter-intro.html" title="Background"> |
| <link rel="prev" href="chapter-intro.html" title="Background"> |
| <link rel="next" href="chapter-gtype.html" title="The GLib Dynamic Type System"> |
| <meta name="generator" content="GTK-Doc V1.14 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> |
| <td><a accesskey="p" href="chapter-intro.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> |
| <td><a accesskey="u" href="chapter-intro.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> |
| <th width="100%" align="center">GObject Reference Manual</th> |
| <td><a accesskey="n" href="chapter-gtype.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="sect1" title="Exporting a C API"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="id545626"></a>Exporting a C API</h2></div></div></div> |
| <p> |
| C APIs are defined by a set of functions and global variables which are usually exported from a |
| binary. C functions have an arbitrary number of arguments and one return value. Each function is thus |
| uniquely identified by the function name and the set of C types which describe the function arguments |
| and return value. The global variables exported by the API are similarly identified by their name and |
| their type. |
| </p> |
| <p> |
| A C API is thus merely defined by a set of names to which a set of types are associated. If you know the |
| function calling convention and the mapping of the C types to the machine types used by the platform you |
| are on, you can resolve the name of each function to find where the code associated to this function |
| is located in memory, and then construct a valid argument list for the function. Finally, all you have to |
| do is trigger a call to the target C function with the argument list. |
| </p> |
| <p> |
| For the sake of discussion, here is a sample C function and the associated 32 bit x86 |
| assembly code generated by GCC on my Linux box: |
| </p> |
| <pre class="programlisting"> |
| static void function_foo (int foo) |
| {} |
| |
| int main (int argc, char *argv[]) |
| { |
| |
| function_foo (10); |
| |
| return 0; |
| } |
| |
| push $0xa |
| call 0x80482f4 <function_foo> |
| </pre> |
| <p> |
| The assembly code shown above is pretty straightforward: the first instruction pushes |
| the hexadecimal value 0xa (decimal value 10) as a 32-bit integer on the stack and calls |
| <code class="function">function_foo</code>. As you can see, C function calls are implemented by |
| gcc by native function calls (this is probably the fastest implementation possible). |
| </p> |
| <p> |
| Now, let's say we want to call the C function <code class="function">function_foo</code> from |
| a Python program. To do this, the Python interpreter needs to: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>Find where the function is located. This probably means finding the binary generated by the C compiler |
| which exports this function.</p></li> |
| <li class="listitem"><p>Load the code of the function in executable memory.</p></li> |
| <li class="listitem"><p>Convert the Python parameters to C-compatible parameters before calling |
| the function.</p></li> |
| <li class="listitem"><p>Call the function with the right calling convention.</p></li> |
| <li class="listitem"><p>Convert the return values of the C function to Python-compatible |
| variables to return them to the Python code.</p></li> |
| </ul></div> |
| <p> |
| </p> |
| <p> |
| The process described above is pretty complex and there are a lot of ways to make it entirely automatic |
| and transparent to C and Python programmers: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>The first solution is to write by hand a lot of glue code, once for each function exported or imported, |
| which does the Python-to-C parameter conversion and the C-to-Python return value conversion. This glue code is then |
| linked with the interpreter which allows Python programs to call Python functions which delegate work to |
| C functions.</p></li> |
| <li class="listitem"><p>Another, nicer solution is to automatically generate the glue code, once for each function exported or |
| imported, with a special compiler which |
| reads the original function signature.</p></li> |
| <li class="listitem"><p>The solution used by GLib is to use the GType library which holds at runtime a description of |
| all the objects manipulated by the programmer. This so-called <span class="emphasis"><em>dynamic type</em></span> |
| <sup>[<a name="id545730" href="#ftn.id545730" class="footnote">1</a>]</sup> |
| library is then used by special generic glue code to automatically convert function parameters and |
| function calling conventions between different runtime domains.</p></li> |
| </ul></div> |
| <p> |
| The greatest advantage of the solution implemented by GType is that the glue code sitting at the runtime domain |
| boundaries is written once: the figure below states this more clearly. |
| </p> |
| <div class="figure"> |
| <a name="id545749"></a><p class="title"><b>Figure 1. </b></p> |
| <div class="figure-contents"><div class="mediaobject" align="center"><img src="glue.png" align="middle"></div></div> |
| </div> |
| <p><br class="figure-break"> |
| |
| Currently, there exist at least Python and Perl generic glue code which makes it possible to use |
| C objects written with GType directly in Python or Perl, with a minimum amount of work: there |
| is no need to generate huge amounts of glue code either automatically or by hand. |
| </p> |
| <p> |
| Although that goal was arguably laudable, its pursuit has had a major influence on |
| the whole GType/GObject library. C programmers are likely to be puzzled at the complexity |
| of the features exposed in the following chapters if they forget that the GType/GObject library |
| was not only designed to offer OO-like features to C programmers but also transparent |
| cross-language interoperability. |
| </p> |
| <div class="footnotes"> |
| <br><hr width="100" align="left"> |
| <div class="footnote"><p><sup>[<a name="ftn.id545730" href="#id545730" class="para">1</a>] </sup> |
| There are numerous different implementations of dynamic type systems: all C++ |
| compilers have one, Java and .NET have one too. A dynamic type system allows you |
| to get information about every instantiated object at runtime. It can be implemented |
| by a process-specific database: every new object created registers the characteristics |
| of its associated type in the type system. It can also be implemented by introspection |
| interfaces. The common point between all these different type systems and implementations |
| is that they all allow you to query for object metadata at runtime. |
| </p></div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr> |
| Generated by GTK-Doc V1.14</div> |
| </body> |
| </html> |
