1
This document describes usage of the uim-scm API and facility for
7
The uim-scm API is responsible for follwing two roles.
9
- Provides Scheme interpreter interfaces to input method plugin
12
- Abstracts Scheme interpreter implementation and narrows its
13
interfaces to provide switcheable base of libuim
15
Other developers should not use this API since the API easily causes
16
fatal crash involving GC if you does not pay attention enough. Be
20
* Protecting lisp objects from GC
22
uim-scm provides the lisp object type named 'uim_lisp'. Since all of
23
the objects are managed by a conservative mark and sweep GC, you
24
have to protect them from undesirable collection. The word
25
'protection' means that instructing GC "it's in use, don't
26
mark". There are two methods of protection.
28
1. static storage protection
30
You can allocate arbitrary static storage as for uim_lisp by
31
uim_scm_gc_protect(). The function must be invoked before using
39
uim_plugin_instance_init(void) {
40
uim_scm_gc_protect(&foo);
41
uim_scm_gc_protect(&bar);
47
You can also protect your lisp objects on stack (i.e. auto
48
storage). See following example.
52
literalize_string(const char *str)
58
uim_scm_gc_protect_stack(&stack_start);
59
form = uim_scm_list2(uim_scm_make_symbol("string-escape"),
60
uim_scm_make_str(str));
61
escaped = uim_scm_c_str(uim_scm_eval(form));
62
uim_scm_gc_unprotect_stack(&stack_start);
68
Combination of uim_scm_gc_protect_stack(),
69
uim_scm_gc_unprotect_stack() and the dummy variable 'stack_start'
70
consists of the stack protection. In this case, the lisp objects
71
'form', anonymous return value of uim_scm_make_symbol(),
72
uim_scm_make_str() and uim_scm_eval() are protected by the method
73
(although some objects may be placed into registers, the registers
74
are also protected implicitly).
76
The 'stack_start' indicates start point of protected region. And
77
uim_scm_gc_protect_stack() instructs the GC protection. After the
78
invocation, the region from stack_start to top of the stack is
79
left untouched at GC marking.
81
Protected stack regions can be nested or duplexed.
83
Be careful to place stack_start. There are some bad examples.
87
uim_lisp form; /* XXX out of protected region */
92
uim_lisp form, stack_start; /* XXX may by out of protected region */
96
uim_lisp stack_start, form; /* ??? may be implementation dependent */
101
This API is not intended to provide all R5RS features. Only 'core'
102
ones to write Scheme-C adapters should be added. Consider how
103
frequently it will be used, and whether it should be written by C,
104
when you want to add an API function.
106
Current implemenation of uim-scm only provides the Siod
107
interpreter. To avoid namespace pollution, all Siod functions are
108
defined as static and wrapped into uim-scm.c by direct inclusion
109
rather than linked via public symbols. After elaboration of uim-scm
110
API, the Scheme interpreter implementation can be switched to
111
another one such as uim-scm-tinyscheme.c or uim-scm-gauche.c. But
112
*.[hc] under uim/ and *.scm are still depending on Siod in several
113
ways. At least full test suite for *.scm files are required to
114
migrate to another Scheme implementation.
added
removed
doc/UIM-SCM
