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.