GNU Info

Info Node: (guile.info)Defining new Scheme procedures in C

(guile.info)Defining new Scheme procedures in C


Next: Converting data between C and Scheme Prev: Executing Scheme code Up: Top
Enter node , (file) or (file)node

Defining new Scheme procedures in C
***********************************

The real interface between C and Scheme comes when you can write new
Scheme procedures in C.  This is done through the routine

 - Libguile high: SCM gh_new_procedure (char *PROC_NAME, SCM (*FN)(),
          int N_REQUIRED_ARGS, int N_OPTIONAL_ARGS, int RESTP)
     `gh_new_procedure' defines a new Scheme procedure.  Its Scheme name
     will be PROC_NAME, it will be implemented by the C function
     (*FN)(), it will take at least N_REQUIRED_ARGS arguments, and at
     most N_OPTIONAL_ARGS extra arguments.

     When the RESTP parameter is 1, the procedure takes a final
     argument: a list of remaining parameters.

     `gh_new_procedure' returns an SCM value representing the procedure.

     The C function FN should have the form

      - Libguile high: SCM fn (SCM REQ1, SCM REQ2, ..., SCM OPT1, SCM
               OPT2, ..., SCM REST_ARGS)
          The arguments are all passed as SCM values, so the user will
          have to use the conversion functions to convert to standard C
          types.

          Examples of C functions used as new Scheme primitives can be
          found in the sample programs `learn0' and `learn1'.


*Rationale:* this is the correct way to define new Scheme procedures in
C.  The ugly mess of arguments is required because of how C handles
procedures with variable numbers of arguments.

*Note:* what about documentation strings?

There are several important considerations to be made when writing the C
routine `(*fn)()'.

First of all the C routine has to return type `SCM'.

Second, all arguments passed to the C funcion will be of type `SCM'.

Third: the C routine is now subject to Scheme flow control, which means
that it could be interrupted at any point, and then reentered.  This
means that you have to be very careful with operations such as
allocating memory, modifying static data ...

Fourth: to get around the latter issue, you can use `GH_DEFER_INTS' and
`GH_ALLOW_INTS'.

 - Macro: GH_DEFER_INTS
 - Macro: GH_ALLOW_INTS
     These macros disable and reenable Scheme's flow control.  They


automatically generated by info2www version 1.2.2.9