| <!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: GObject Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <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.25.1 (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="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="chapter-intro.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="chapter-intro.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="chapter-gtype.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="id-1.3.2.6"></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 a Linux computer: |
| </p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2 |
| 3 |
| 4 |
| 5 |
| 6 |
| 7 |
| 8 |
| 9 |
| 10 |
| 11 |
| 12 |
| 13 |
| 14 |
| 15 |
| 16</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> |
| <span class="function">function_foo</span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="normal"> foo</span><span class="symbol">)</span> |
| <span class="cbracket">{</span> |
| <span class="cbracket">}</span> |
| |
| <span class="type">int</span> |
| <span class="function">main</span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="normal"> argc</span><span class="symbol">,</span> |
| <span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">argv</span><span class="symbol">[])</span> |
| <span class="cbracket">{</span> |
| <span class="normal"> </span><span class="function">function_foo</span><span class="normal"> </span><span class="symbol">(</span><span class="number">10</span><span class="symbol">);</span> |
| |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span> |
| <span class="cbracket">}</span> |
| |
| <span class="normal">push $</span><span class="number">0xa</span> |
| <span class="normal">call </span><span class="number">0x80482f4</span><span class="normal"> </span><span class="symbol"><</span><span class="normal">function_foo</span><span class="symbol">></span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <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 as 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" style="list-style-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" style="list-style-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> |
| <a href="#ftn.id-1.3.2.6.6.1.3.1.2" class="footnote" name="id-1.3.2.6.6.1.3.1.2"><sup class="footnote">[1]</sup></a> |
| 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="id-1.3.2.6.6.2"></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 style="width:100; text-align:left;margin-left: 0"> |
| <div id="ftn.id-1.3.2.6.6.1.3.1.2" class="footnote"><p><a href="#id-1.3.2.6.6.1.3.1.2" class="para"><sup class="para">[1] </sup></a> |
| 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.25.1</div> |
| </body> |
| </html> |