mirrors/ecl
1
Fork 0
mirror of https://gitlab.com/embeddable-common-lisp/ecl.git synced 2026-01-12 20:31:55 -08:00
Code Issues Projects Releases Packages Wiki Activity
ecl/doc/ref_embed.xmlf
Daniel Kochmański 1a3aecc2d6 doc: add documentation as doc subdirectory 
Signed-off-by: Daniel Kochmański <daniel@turtleware.eu>
2015-08-04 21:55:36 +02:00

548 lines
No EOL
18 KiB
XML
Raw Blame History

<?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>SIGALTSTACK_SIZE</constant></entry>
<entry><type>cl_index</type></entry>
<entry><constant>1</constant></entry>
<entry>If nonzero, run C signal handler in an alternative
signal. A small value is automatically incremented.</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:
-->
Reference in a new issue View git blame Copy permalink