## Embedding

### Embedding Reference

`CL_CATCH_ALL`

Create a protected region.

#### C Macro

      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.
       */

##### Description

This is a set of three macros that create an `UNWIND-PROTECT` region that prevents any nonlocal transfer of control to outer loops. In the Lisp speak, the previous code is equivalent to

    (block nil
      (unwind-protect
         (progn
            ;; Code that is protected
    	)
        (return nil)))

As explained in ref.embed.cl_unwind_protect,it is normally advisable to set up an unwind-protect frame to avoid the embedded lisp code to perform arbitary transfers of control.

##### See also

`cl_unwind_protect`

`CL_UNWIND_PROTECT`

Create a protected region.

#### C Macro

      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.
       */

##### Description

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:

- In a normal program exit, caused by `ext:quit`, &ECL; unwinds up to the outermost frame, which may be an ref.embed.cl_catch_all or ref.embed.cl_unwind_protect macro.

Besides this, normal mechanisms for exit, such as `ext:quit`, and uncaught exceptions, such as serious signals (ext.signals.synchronous), are best handled using unwind-protect blocks.

##### See also

ref.embed.cl_catch_all

`cl_boot`

Setup the lisp environment.

#### Function

        int cl_boot
        int argc
        char **argv

`argc`

- An integer with the number of arguments to this program.

`argv`

- A vector of strings with the arguments to this program.

##### Description

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 ref.embed.ecl_set_option and ref.embed.ecl_get_option.

`cl_shutdown`

Close the lisp environment.

#### Function

        int cl_shutdown
        void

##### Description

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.

`ecl_set_option`

Set a boot option.

#### Function

        void ecl_set_option
        int option
        cl_fixnum value

`option`

- An integer from table.boot_options.

`value`

- A `cl_index` value for this option.

##### Description

This functions sets the value of different options that have to be customized before &ECL; boots. The table of options and default values [table.boot_options] shows that some of them are boolean, and some of them are unsigned integers.

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 Ctrl-C, floating point exceptions, etc.

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.

##### Boot options for embedded &ECL;

Name (`ECL_OPT_*`) | Type | Default | Description
`INCREMENTAL_GC` | `boolean` | `TRUE` | Activate generational garbage collector.
`TRAP_SIGSEGV` | `boolean` | `TRUE` | Capture SIGSEGV signals.
`TRAP_SIGFPE` | `boolean` | `TRUE` | Capture floating point exceptions.
`TRAP_SIGINT` | `boolean` | `TRUE` | Capture user interrupts.
`TRAP_SIGILL` | `boolean` | `TRUE` | Capture SIGILL exception.
`TRAP_INTERRUPT_SIGNAL` | `boolean` | `TRUE` | Capture the signal that implements `mp:interrupt-process`.
`SIGNAL_HANDLING_THREAD` | `boolean` | `TRUE` | Create a signal to capture and process asynchronous threads (See ext.signals.asynchronous-handler).
`BOOTED` | `boolean` | `TRUE/FALSE` | Has &ECL; booted (read only).
`BIND_STACK_SIZE` | `cl_index` | `8192` | Size of stack for binding special variables.
`BIND_STACK_SAFETY_AREA` | `cl_index` | `128` |
`FRAME_STACK_SIZE` | `cl_index` | `2048` | Size of stack for nonlocal jumps.
`FRAME_STACK_SAFETY_AREA` | `cl_index` | `128` |
`LISP_STACK_SIZE` | `cl_index` | `32768` | Size of interpreter stack.
`LISP_STACK_SAFETY_AREA` | `cl_index` | `128` |
`C_STACK_SIZE` | `cl_index` | `131072` | Size of C stack (not exact).
`C_STACK_SAFETY_AREA` | `cl_index` | `4192` |
`SIGALTSTACK_SIZE` | `cl_index` | `1` | If nonzero, run C signal handler in an alternative signal. A small value is automatically incremented.
`THREAD_INTERRUPT_SIGNAL` | `unsigned int` | `0` | If nonzero, specify the unix signal which is used to communicate different Lisp threads.

`ecl_get_option`

Read the value of a boot option.

#### Function

        cl_fixnum ecl_get_option
        int option

`option`

- An integer from table.boot_options.

##### Description

This functions reads the value of different options that have to be customized before &ECL; boots. The table of options and default values is table.boot_options.

`ecl_clear_interrupts`

Clear all pending signals and exceptions.

#### Macro

        ecl_clear_interrupts

##### Description

This macro clears all pending interrupts.

##### See also

ref.embed.ecl_disable_interrupts and ref.embed.ecl_enable_interrupts.

`ecl_disable_interrupts`

Postpone handling of signals and exceptions.

#### Macro

        ecl_disable_interrupts

##### Description

This macro sets a thread-local flag indicating that all received signals should be queued for later processing.

##### See also

ref.embed.ecl_enable_interrupts and ref.embed.ecl_clear_interrupts.

`ecl_enable_interrupts`

Activate handling of signals and exceptions.

#### Macro

        ecl_enable_interrupts

##### Description

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.

##### See also

ref.embed.ecl_disable_interrupts and ref.embed.ecl_clear_interrupts.