<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<chapter>
<title>Embedding</title>
<section xml:id="ext.embed.dict">
<title>Embedding Reference</title>

<!-- ====================================================================== -->
<!-- CL_CATCH_ALL                                                           -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.cl_catch_all">
 <refnamediv>
  <refname><function>CL_CATCH_ALL</function></refname>
  <refpurpose>Create a protected region.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>C Macro</title>
<programlisting>
  cl_env_ptr env = ecl_process_env();
  CL_CATCH_ALL_BEGIN(env) {
    /*
     * Code that is protected. Uncaught lisp conditions, THROW,
     * signals such as SIGSEGV and SIGBUS may cause jump to
     * this region.
     */
  } CL_CATCH_ALL_IF_CAUGHT {
    /*
     * If the exception, lisp condition or other control transfer
     * is caught, this code is executed.
     */
  } CL_CATCH_ALL_END
  /*
   * In all cases we exit here.
   */
</programlisting>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>This is a set of three macros that create an
  <function>UNWIND-PROTECT</function> region that prevents any nonlocal transfer
  of control to outer loops. In the Lisp speak, the previous code is
  equivalent to</para>
<programlisting>
(block nil
  (unwind-protect
     (progn
        ;; Code that is protected
	)
    (return nil)))
</programlisting>

   <para>As explained in <xref linkend="ref.embed.cl_unwind_protect" xrefstyle="select: label"/>,it is normally advisable to set up an unwind-protect frame to avoid the embedded lisp code to perform arbitary transfers of control.</para>
 </refsect1>

 <refsect1>
  <title>See also</title>

  <para><link linkend="ref.embed.cl_unwind_protect"><function>cl_unwind_protect</function></link></para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- CL_UNWIND_PROTECT                                                      -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.cl_unwind_protect">
 <refnamediv>
  <refname><function>CL_UNWIND_PROTECT</function></refname>
  <refpurpose>Create a protected region.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>C Macro</title>
<programlisting>
  cl_env_ptr env = ecl_process_env();
  CL_UNWIND_PROTECT_BEGIN(env) {
    /*
     * Code that is protected. Uncaught lisp conditions, THROW,
     * signals such as SIGSEGV and SIGBUS may cause jump to
     * this region.
     */
  } CL_UNWIND_PROTECT_EXIT {
    /*
     * If the exception, lisp condition or other control transfer
     * is caught, this code is executed. After this code, the
     * process will jump to the original destination of the
     * THROW, GOTO or other control statement that was interrupted.
     */
  } CL_UNWIND_PROTECT_END
  /*
   * We only exit here if NO nonlocal jump was interrupted.
   */
</programlisting>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

   <para>When embedding &ECL; it is normally advisable to set up an
   unwind-protect frame to avoid the embedded lisp code to perform arbitary
   transfers of control. Furthermore, the unwind protect form will be
   used in at least in the following ocasions:</para>
   <itemizedlist>
    <listitem>
     <para>In a normal program exit, caused by <function>ext:quit</function>,
     &ECL; unwinds up to the outermost frame, which may be an <xref
     linkend="ref.embed.cl_catch_all"/> or <xref
     linkend="ref.embed.cl_unwind_protect"/> macro.</para>
    </listitem>
   </itemizedlist>

   <para>Besides this, normal mechanisms for exit, such as
   <function>ext:quit</function>, and uncaught exceptions, such as serious
   signals (<xref linkend="ext.signals.synchronous"/>), are best handled using
   unwind-protect blocks.</para>
 </refsect1>

 <refsect1>
  <title>See also</title>

  <para><xref linkend="ref.embed.cl_catch_all"/></para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- cl_boot()                                                              -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.cl_boot">
 <refnamediv>
  <refname><function>cl_boot</function></refname>
  <refpurpose>Setup the lisp environment.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Function</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef>int <function>cl_boot</function></funcdef>
    <paramdef>int <parameter>argc</parameter></paramdef>
    <paramdef>char **<parameter>argv</parameter></paramdef>
   </funcprototype>
  </funcsynopsis>
  <variablelist>
   <varlistentry>
    <term><replaceable>argc</replaceable></term>
    <listitem><para>An integer with the number of arguments to this program.</para></listitem>
    <term><replaceable>argv</replaceable></term>
    <listitem><para>A vector of strings with the arguments to this program.</para></listitem>
   </varlistentry>
  </variablelist>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>This function must be called before any other function from the &ECL;
  library, including the creation of any lisp object or evaluating any lisp code.
  The only exception are <xref linkend="ref.embed.ecl_set_option"/>
  and <xref linkend="ref.embed.ecl_get_option"/>.
  </para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- cl_shutdown()                                                          -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.cl_shutdown">
 <refnamediv>
  <refname><function>cl_shutdown</function></refname>
  <refpurpose>Close the lisp environment.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Function</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef>int <function>cl_shutdown</function></funcdef>
    <paramdef>void</paramdef>
   </funcprototype>
  </funcsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>This function must be called before exiting a program that uses the &ECL;
  environment. It performs some cleaning, including the execution of any
  finalizers, unloading shared libraries and deleting temporary files that were
  created by the compiler.
  </para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- ecl_set_option()                                                       -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.ecl_set_option">
 <refnamediv>
  <refname><function>ecl_set_option</function></refname>
  <refpurpose>Set a boot option.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Function</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef>void <function>ecl_set_option</function></funcdef>
    <paramdef>int <parameter>option</parameter></paramdef>
    <paramdef>cl_fixnum <parameter>value</parameter></paramdef>
   </funcprototype>
  </funcsynopsis>
  <variablelist>
   <varlistentry>
    <term><replaceable>option</replaceable></term>
    <listitem><para>An integer from <xref linkend="table.boot_options"/>.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><replaceable>value</replaceable></term>
    <listitem><para>A <type>cl_index</type> value for this option.</para></listitem>
   </varlistentry>
  </variablelist>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>This functions sets the value of different options that have
  to be customized <emphasis>before</emphasis> &ECL; boots. The table
  of options and default values [<xref linkend="table.boot_options"/>]
  shows that some of them are boolean, and some of them are unsigned
  integers.</para>

  <para>We distinguish three sets of values. The first set determines
  whether &ECL; handles certain exceptions, such as access to forbidden
  regions of memory, interrupts via <keycombo>Ctrl-C</keycombo>, floating point
  exceptions, etc.</para>

  <para>The second set is related to the sizes of different
  stacks. Currently &ECL; uses four stacks: a bind stack for keeping
  assignments to special variables; a frame stack for implementing
  blocks, tagbodys and catch points; an interpreter stack for
  evaluating bytecodes, and finally the machine or C stack, of the
  computer we run in. We can set the expected size of these stacks,
  together with the size of a safety area which, if penetrated, will
  lead to the generation of a correctable error.</para>

  <table xml:id="table.boot_options">
    <title>Boot options for embedded &ECL;</title>
    <tgroup cols="4">
      <thead>
      <row>
       <entry>Name (<constant>ECL_OPT_*</constant>)</entry>
       <entry>Type</entry>
       <entry>Default</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><constant>INCREMENTAL_GC</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Activate generational garbage collector.</entry>
      </row>
      <row>
       <entry><constant>TRAP_SIGSEGV</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Capture SIGSEGV signals.</entry>
      </row>
      <row>
       <entry><constant>TRAP_SIGFPE</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Capture floating point exceptions.</entry>
      </row>
      <row>
       <entry><constant>TRAP_SIGINT</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Capture user interrupts.</entry>
      </row>
      <row>
       <entry><constant>TRAP_SIGILL</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Capture SIGILL exception.</entry>
      </row>
      <row>
       <entry><constant>TRAP_INTERRUPT_SIGNAL</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Capture the signal that implements
       <function>mp:interrupt-process</function>.</entry>
      </row> 
      <row>
       <entry><constant>SIGNAL_HANDLING_THREAD</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE</constant></entry>
       <entry>Create a signal to capture and process asynchronous threads (See
       <xref linkend="ext.signals.asynchronous-handler"/>).</entry>
      </row> 
      <row>
       <entry><constant>BOOTED</constant></entry>
       <entry><type>boolean</type></entry>
       <entry><constant>TRUE/FALSE</constant></entry>
       <entry>Has &ECL; booted (read only).</entry>
      </row>
      <row>
       <entry><constant>BIND_STACK_SIZE</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>8192</constant></entry>
       <entry>Size of stack for binding special variables.</entry>
      </row>
      <row>
       <entry><constant>BIND_STACK_SAFETY_AREA</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>128</constant></entry>
       <entry></entry>
      </row>
      <row>
       <entry><constant>FRAME_STACK_SIZE</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>2048</constant></entry>
       <entry>Size of stack for nonlocal jumps.</entry>
      </row>
      <row>
       <entry><constant>FRAME_STACK_SAFETY_AREA</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>128</constant></entry>
       <entry></entry>
      </row>
      <row>
       <entry><constant>LISP_STACK_SIZE</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>32768</constant></entry>
       <entry>Size of interpreter stack.</entry>
      </row>
      <row>
       <entry><constant>LISP_STACK_SAFETY_AREA</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>128</constant></entry>
       <entry></entry>
      </row>
      <row>
       <entry><constant>C_STACK_SIZE</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>131072</constant></entry>
       <entry>Size of C stack (not exact).</entry>
      </row>
      <row>
       <entry><constant>C_STACK_SAFETY_AREA</constant></entry>
       <entry><type>cl_index</type></entry>
       <entry><constant>4192</constant></entry>
       <entry></entry>
      </row>
      <row>
       <entry><constant>THREAD_INTERRUPT_SIGNAL</constant></entry>
       <entry><type>unsigned int</type></entry>
       <entry><constant>0</constant></entry>
       <entry>If nonzero, specify the unix signal which is used to
       communicate different Lisp threads.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>

 </refsect1>

</refentry>

<!-- ====================================================================== -->
<!-- ecl_get_option()                                                       -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.ecl_get_option">
 <refnamediv>
  <refname><function>ecl_get_option</function></refname>
  <refpurpose>Read the value of a boot option.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Function</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef>cl_fixnum <function>ecl_get_option</function></funcdef>
    <paramdef>int <parameter>option</parameter></paramdef>
   </funcprototype>
  </funcsynopsis>
  <variablelist>
   <varlistentry>
    <term><replaceable>option</replaceable></term>
    <listitem><para>An integer from <xref linkend="table.boot_options"/>.</para></listitem>
   </varlistentry>
  </variablelist>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>This functions reads the value of different options that have
  to be customized <emphasis>before</emphasis> &ECL; boots. The table
  of options and default values is <xref linkend="table.boot_options"/>.
  </para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- ecl_clear_interrupts()                                               -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.ecl_clear_interrupts">
 <refnamediv>
  <refname><function>ecl_clear_interrupts</function></refname>
  <refpurpose>Clear all pending signals and exceptions.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Macro</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef><function>ecl_clear_interrupts</function></funcdef>
    <paramdef></paramdef>
   </funcprototype>
  </funcsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>This macro clears all pending interrupts.
  </para>
 </refsect1>

 <refsect1>
  <title>See also</title>
  <para> <xref linkend="ref.embed.ecl_disable_interrupts"/> and <xref
  linkend="ref.embed.ecl_enable_interrupts"/>.
  </para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- ecl_disable_interrupts()                                               -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.ecl_disable_interrupts">
 <refnamediv>
  <refname><function>ecl_disable_interrupts</function></refname>
  <refpurpose>Postpone handling of signals and exceptions.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Macro</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef><function>ecl_disable_interrupts</function></funcdef>
    <paramdef></paramdef>
   </funcprototype>
  </funcsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>This macro sets a thread-local flag indicating that all received
  signals should be queued for later processing.
  </para>
 </refsect1>

 <refsect1>
  <title>See also</title>
  <para><xref linkend="ref.embed.ecl_enable_interrupts"/> and <xref
  linkend="ref.embed.ecl_clear_interrupts"/>.
  </para>
 </refsect1>
</refentry>

<!-- ====================================================================== -->
<!-- ecl_enable_interrupts()                                                -->
<!-- ====================================================================== -->

<refentry xml:id="ref.embed.ecl_enable_interrupts">
 <refnamediv>
  <refname><function>ecl_enable_interrupts</function></refname>
  <refpurpose>Activate handling of signals and exceptions.</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <title>Macro</title>
  <funcsynopsis>
   <?dbhtml funcsynopsis-style='ansi'?>
   <funcprototype>
    <funcdef><function>ecl_enable_interrupts</function></funcdef>
    <paramdef></paramdef>
   </funcprototype>
  </funcsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>This macro sets a thread-local flag indicating that all received
  signals can be handled. If there are any pending signals, they will be
  immediately processed.
  </para>
 </refsect1>

 <refsect1>
  <title>See also</title>
  <para><xref
  linkend="ref.embed.ecl_disable_interrupts"/> and <xref
  linkend="ref.embed.ecl_clear_interrupts"/>.
  </para>
 </refsect1>
</refentry>
</section>
</chapter>
</book>
<!-- Keep this comment at the end of the file
      Local variables:
      mode: nxml
      sgml-parent-document: "ecl.xml"
      sgml-indent-step: 1
      nxml-child-indent: 1
      nxml-outline-child-indent: 1
      fill-column: 79
      End:
 -->
