docs/reference/gobject/html/ch01s02.html

<!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">&lt;</span><span class="normal">function_foo</span><span class="symbol">&gt;</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>