X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=docs%2Freference%2Fdispatch.sgml;fp=docs%2Freference%2Fdispatch.sgml;h=7a811de2f9a8fdd0a33c5c2202312b2ded28ed79;hb=ee81c9edf038fbd02460c512e64504bdf994d91e;hp=0000000000000000000000000000000000000000;hpb=7637a8d2987f253973b1f1e0eac52e49490254db;p=rodin%2Fchimara.git diff --git a/docs/reference/dispatch.sgml b/docs/reference/dispatch.sgml new file mode 100644 index 0000000..7a811de --- /dev/null +++ b/docs/reference/dispatch.sgml @@ -0,0 +1,39 @@ + + + + +The Dispatch Layer +3 +CHIMARA Library + + +The Dispatch Layer +Calling Glk functions dynamically + + +Description + +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 — determining the capabilities and interfaces of Glk at run-time. + + +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. + + +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.) + + +How This Works + +The dispatch layer is implemented in a C source file, gi_dispa.c, and its header, gi_dispa.h. This code is platform-independent — it is identical in every library, just as the glk.h header file is identical in every library. Each library author should download the gi_dispa.c and gi_dispa.h files from the Glk web site, and compile them unchanged into the library. + + +This code is mostly external to Glk; it operates by calling the documented Glk API, not library internals. This is how gi_dispa.c 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; gi_dispa.c (and no one else) calls these functions. These functions are simple and should not make life much harder for library implementors. + + +The dispatch layer then provides a dispatch API. The heart of this is the gidispatch_call() function, which allows you to call any Glk function (specified by number) and pass in a list of arguments in a standardized way. You may also make use of gidispatch_prototype(), 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. + + + +