docs/reference/dispatch.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <refentry id="chimara-The-Dispatch-Layer">
   6 <refmeta>
   7 <refentrytitle>The Dispatch Layer</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>The Dispatch Layer</refname>
  13 <refpurpose>Calling Glk functions dynamically</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 The material described in this section is not part of the Glk API per se. It is an external layer, lying on top of Glk, which allows a program to invoke Glk dynamically &mdash; determining the capabilities and interfaces of Glk at run-time.
  19 </para>
  20 <para>
  21 This is most useful for virtual machines and other run-time systems, which want to use Glk without being bound to a particular version of the Glk API. In other words, a VM can export Glk to VM programs, without hard-wiring a list of Glk functions within itself. If a new Glk library is released, with new functions, the VM can simply link in the library; the new functions will be available to VM programs without further work.
  22 </para>
  23 <para>
  24 If you are writing a C program which uses the Glk API, you can ignore this section entirely. If you are writing a VM which uses Glk, you need to read it. If you are implementing a Glk library, you should also read it. (There are some additional interfaces which your library must support for the dispatch layer to work right.)
  25 </para>
  26 <refsect2 id="chimara-How-This-Works">
  27 <title>How This Works</title>
  28 <para>
  29 The dispatch layer is implemented in a C source file, <filename>gi_dispa.c</filename>, and its header, <filename class="headerfile">gi_dispa.h</filename>. This code is platform-independent &mdash; it is identical in every library, just as the <filename class="headerfile">glk.h</filename> header file is identical in every library. Each library author should download the <filename>gi_dispa.c</filename> and <filename class="headerfile">gi_dispa.h</filename> files from the Glk web site, and compile them unchanged into the library.
  30 </para>
  31 <para>
  32 This code is mostly external to Glk; it operates by calling the documented Glk API, not library internals. This is how <filename>gi_dispa.c</filename> can be platform-independent. However, the dividing line is not perfect. There are a few extra functions, not part of the Glk API, which the library must implement; <filename>gi_dispa.c</filename> (and no one else) calls these functions. These functions are simple and should not make life much harder for library implementors.
  33 </para>
  34 <para>
  35 The dispatch layer then provides a dispatch API. The heart of this is the <link linkend="gidispatch-call"><function>gidispatch_call()</function></link> function, which allows you to call <emphasis>any</emphasis> Glk function (specified by number) and pass in a list of arguments in a standardized way. You may also make use of <link linkend="gidispatch-prototype"><function>gidispatch_prototype()</function></link>, which gives you the proper format of that list for each function. Ancilliary functions let you enumerate the functions and constants in the Glk API.
  36 </para>
  37 </refsect2>
  38 </refsect1>
  39 </refentry>