/usr/share/doc/uim/UIM-SCM is in uim 1:1.8.6+gh20180114.64e3173-2build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | This document describes usage of the uim-scm API and facility for
developers.
* Abstract
The uim-scm API is responsible for following two roles.
- Provides Scheme interpreter interfaces to input method plugin
developers
- Abstracts Scheme interpreter implementation and narrows its
interfaces to provide switcheable base of libuim
Other developers should not use this API since the API easily causes
fatal crash involving GC if you does not pay attention enough. Be
careful.
* Protecting lisp objects from GC
uim-scm provides the lisp object type named 'uim_lisp'. Since all of
the objects are managed by a conservative mark and sweep GC, you
have to protect them from undesirable collection. The word
'protection' means that instructing GC "It's in use, don't
mark". There are two methods of protection.
1. static storage protection
You can allocate arbitrary static storage as for uim_lisp by
uim_scm_gc_protect(). The function must be invoked before using
the variables.
static uim_lisp foo;
static uim_lisp bar;
void
uim_plugin_instance_init(void) {
uim_scm_gc_protect(&foo);
uim_scm_gc_protect(&bar);
}
2. stack protection
You can also protect your lisp objects on stack (i.e. auto
storage). See following example.
char *
literalize_string(const char *str)
{
uim_gc_gate_func_ptr func_body;
void *ret;
func_body = (uim_gc_gate_func_ptr)literalize_string_internal;
ret = uim_scm_call_with_gc_ready_stack(func_body, (void *)str);
return (char *)ret;
}
static char *
literalize_string_internal(const char *str)
{
uim_lisp form;
char *escaped;
form = uim_scm_list2(uim_scm_make_symbol("string-escape"),
uim_scm_make_str(str));
escaped = uim_scm_c_str(uim_scm_eval(form));
return escaped;
}
All function that uses stack-placed uim_lisp must be called via
uim_scm_call_with_gc_ready_stack() as above. It setups the base address of
'protected' stack region. In this case, the lisp objects 'form', anonymous
return value of uim_scm_make_symbol(), uim_scm_make_str() and
uim_scm_eval() are protected by the method (although some objects may be
placed into registers, the registers are also protected implicitly).
The function type uim_gc_gate_func_ptr is defined as follows in
uim-scm.h. Since its arguments and return type are fixed to (void *),
passing multiple arguments to a function need temporary struct. See
uim_scm_error() in uim-scm.c for example.
typedef void *(*uim_gc_gate_func_ptr)(void *);
The 'protected' stack region can be
nested. i.e. uim_scm_call_with_gc_ready_stack() can be invoked from a
function invoked from uim_scm_call_with_gc_ready_stack().
* Internal
The uim-scm API is not intended to provide all R5RS features. Only 'core'
ones to write Scheme-C adapters should be added. Consider how
frequently it will be used, and whether it should be written by C,
when you want to add an API function.
Current implemenation of uim-scm only provides the SigScheme interpreter. To
avoid namespace pollution, all SigScheme functions and variables are defined
as static and wrapped into uim-scm.c by direct inclusion rather than linked
via public symbols. After elaboration of uim-scm API, the Scheme interpreter
implementation can be switched to another one such as uim-scm-scheme48.c or
uim-scm-gauche.c.
|