fix lots of typos, some of which were reported by Leonardo Boshell.
[platform/upstream/glib.git] / docs / reference / gobject / tut_intro.xml
1 <chapter>
2 <title>Background</title>
3
4 <para>
5 GObject, and its lower-level type system, GType, are used by GTK+ and most Gnome libraries to
6 provide:
7 <itemizedlist>
8 <listitem><para>object-oriented C-based APIs and</para></listitem>
9 <listitem><para>automatic transparent API bindings to other compiled 
10 or interpreted languages.</para></listitem>
11 </itemizedlist>
12 </para>
13
14 <para>A lot of programmers are used to work with compiled-only or dynamically interpreted-only
15 languages and do not understand the challenges associated with cross-language interoperability.
16 This introduction tries to provide an insight into these challenges. describes briefly 
17 the solution choosen by GLib.
18 </para>
19
20 <para>The following chapters go into greater detail into how GType and GObject work and
21 how you can use them as a C programmer. It is useful to keep in mind that
22 allowing access to C objects from other interpreted languages was one of the major design
23 goals: this can often explain the sometimes rather convoluted APIs and features present
24 in this library.
25 </para>
26
27 <sect1>
28 <title>Data types and programming</title>
29
30 <para>
31 One could say (I have seen such definitions used in some textbooks on programming language theory)
32 that a programming language is merely a way to create data types and manipulate them. Most languages
33 provide a number of language-native types and a few primitives to create more complex types based
34 on these primitive types.
35 </para>
36
37 <para>
38 In C, the language provides types such as <emphasis>char</emphasis>, <emphasis>long</emphasis>, 
39 <emphasis>pointer</emphasis>. During compilation of C code, the compiler maps these
40 language types to the compiler's target architecture machine types. If you are using a C interpreter
41 (I have never seen one myself but it is possible :), the interpreter (the program which interprets 
42 the source code and executes it) maps the language types to the machine types of the target machine at 
43 runtime, during the program execution (or just before execution if it uses a Just In Time compiler engine).
44 </para>
45
46 <para>Perl and Python which are interpreted languages do not really provide type definitions similar
47 to those used by C. Perl and Python programmers manipulate variables and the type of the variables
48 is decided only upon the first assignment or upon the first use which forces a type on the variable.
49 The interpreter also often provides a lot of automatic conversions from one type to the other. For example,
50 in Perl, a variable which holds an integer can be automatically converted to a string given the
51 required context:
52 <programlisting>
53 my $tmp = 10;
54 print "this is an integer converted to a string:" . $tmp . "\n";
55 </programlisting>
56 Of course, it is also often possible to explicitely specify conversions when the default conversions provided
57 by the language are not intuitive.
58 </para>
59
60 </sect1>
61
62 <sect1>
63 <title>Exporting a C API</title>
64
65 <para>C APIs are defined by a set of functions and global variables which are usually exported from a 
66 binary. C functions have an arbitrary number of arguments and one return value. Each function is thus
67 uniquely identified by the function name and the set of C types which describe the function arguments
68 and return value. The global variables exported by the API are similarly identified by their name and 
69 their type.
70 </para>
71
72 <para>
73 A C API is thus merely defined by a set of names to which a set of types are associated. If you know the
74 function calling convention and the mapping of the C types to the machine types used by the platform you 
75 are on, you can resolve the name of each function to find where the code associated to this function 
76 is located in memory, and then construct a valid argument list for the function. Finally, all you have to 
77 do is triger a call to the target C function with the argument list.
78 </para>
79
80 <para>
81 For the sake of discussion, here is a sample C function and the associated 32 bit x86 
82 assembly code generated by gcc on my linux box:
83 <programlisting>
84 static void function_foo (int foo)
85 {}
86
87 int main (int argc, char *argv[])
88 {
89
90         function_foo (10);
91
92         return 0;
93 }
94
95 push   $0xa
96 call   0x80482f4 &lt;function_foo>
97 </programlisting>
98 The assembly code shown above is pretty straightforward: the first instruction pushes
99 the hexadecimal value 0xa (decimal value 10) as a 32 bit integer on the stack and calls 
100 <function>function_foo</function>. As you can see, C function calls are implemented by
101 gcc by native function calls (this is probably the fastest implementation possible).
102 </para>
103
104 <para>
105 Now, let's say we want to call the C function <function>function_foo</function> from 
106 a python program. To do this, the python interpreter needs to:
107 <itemizedlist>
108 <listitem><para>Find where the function is located. This means probably find the binary generated by the C compiler
109 which exports this functions.</para></listitem>
110 <listitem><para>Load the code of the function in executable memory.</para></listitem>
111 <listitem><para>Convert the python parameters to C-compatible parameters before calling 
112 the function.</para></listitem>
113 <listitem><para>Call the function with the right calling convention</para></listitem>
114 <listitem><para>Convert the return values of the C function to python-compatible
115 variables to return them to the python code.</para></listitem>
116 </itemizedlist>
117 </para>
118
119 <para>The process described above is pretty complex and there are a lot of ways to make it entirely automatic
120 and transparent to the C and the Python programmers:
121 <itemizedlist>
122 <listitem><para>The first solution is to write by hand a lot of glue code, once for each function exported or imported,
123 which does the python to C parameter conversion and the C to python return value conversion. This glue code is then 
124 linked with the interpreter which allows python programs to call a python functions which delegates the work to the 
125 C function.</para></listitem>
126 <listitem><para>Another nicer solution is to automatically generate the glue code, once for each function exported or
127 imported, with a special compiler which
128 reads the original function signature.</para></listitem>
129 <listitem><para>The solution used by GLib is to use the GType library which holds at runtime a description of
130 all the objects manipulated by the programmer. This so-called <emphasis>dynamic type</emphasis><footnote>
131 <para>
132         There are numerous different implementations of dynamic type systems: all C++ 
133         compilers have one, Java and .NET have one too. A dynamic type system allows you
134         to get information about every instantiated object at runtime. It can be implemented
135         by a process-specific database: every new object created registers the characteristics 
136         of its associated type in the type system. It can also be implemented by introspection
137         interfaces. The common point between all these different type systems and implementations
138         is that they all allow you to query for object metadata at runtime.
139 </para>
140 </footnote>
141
142  library is then
143 used by special generic glue code to automatically convert function parameters and function calling conventions
144 between different runtime domains.</para></listitem>
145 </itemizedlist>
146 The greatest advantage of the solution implemented by GType is that the glue code sitting at the runtime domain 
147 boundaries is written once: the figure below states this more clearly.
148 <figure>
149   <mediaobject>
150     <imageobject> <!-- this is for HTML output -->
151       <imagedata fileref="glue.png" format="PNG" align="center"/>
152     </imageobject>
153     <imageobject> <!-- this is for PDF output -->
154       <imagedata fileref="glue.jpg" format="JPG" align="center"/>
155     </imageobject>
156   </mediaobject>
157 </figure>
158
159 Currently, there exist at least Python and Perl generic glue code which makes it possible to use
160 C objects written with GType directly in Python or Perl, with a minimum amount of work: there
161 is no need to generate huge amounts of glue code either automatically or by hand.
162 </para>
163
164 <para>Although that goal was arguably laudable, its pursuit has had a major influence on
165 the whole GType/GObject library. C programmers are likely to be puzzled at the complexity 
166 of the features exposed in the following chapters if they forget that the GType/GObject library
167 was not only designed to offer OO-like features to C programmers but also transparent 
168 cross-language interoperability.
169 </para>
170
171 </sect1>
172
173 </chapter>