► |  | Inside: Racket C API

I | Inside Racket CS
II | Inside Racket BC (3m and CGC)
III | Appendices
| Index

▼ | I | Inside Racket CS

1 | Overview (CS)
2 | Embedding into a Program (CS)
3 | Values and Types (CS)
4 | Calling Procedures (CS)
5 | Starting and Declaring Initial Modules (CS)
6 | Evaluation and Running Modules (CS)
7 | Managing OS-Level Threads (CS)

top ← prev up next →

### 4`` Calling Procedures (CS)

As an entry point into Racket, C programs should normally call Racket procedures by using racket_apply, which calls the procedure in the initial Racket thread of the main Racket place. Chez Scheme entry points such as Scall0 and Scall directly call a procedure outside of any Racket thread, which will not work correctly with Racket facilities such as threads, parameters, continuations, or continuation marks.

The functions in this section are meant to be used as an entry point to Racket, but not as a re-entry point. When Racket calls a C function that in turn calls back into Racket, the best approach is to use the FFI (see The Racket Foreign Interface) so that the C call recieves a Racket callback that is wrapped as a plain C callback. That way, the FFI can handle the details of boundary crossings between Racket and C.

ptr |  | racket_apply | ( | ptr proc,
|  |  |  | ptr arg_list)

Applies the Racket procedure proc to the list of arguments arg_list. The procedure is called in the original Racket thread of the main Racket place. Applying proc must not raise an exception or otherwise escape from the call to proc.

The result is a list of result values, where a single result from proc causes racket_apply to return a list of length one.

Other Racket threads can run during the call to proc. At the point that proc results, all Racket thread scheduling in the main Racket place is suspended. No garbage collections will occur, so other Racket places can block waiting for garbage collection.

ptr |  | Scall0 | ( | ptr proc)

ptr |  | Scall1 | ( | ptr proc,
|  |  |  | ptr arg1)

ptr |  | Scall2 | ( | ptr proc,
|  |  |  | ptr arg1,
|  |  |  | ptr arg2)

ptr |  | Scall3 | ( | ptr proc,
|  |  |  | ptr arg1,
|  |  |  | ptr arg2,
|  |  |  | ptr arg3)

Applies the Chez Scheme procedure proc to zero, one, two, or three arguments. Beware that not all Racket procedures are Chez Scheme procedures. (For example, an instance of a structure type that has prop:procedure is not a Chez Scheme procedure.)

The procedure is called outside of any Racket thread, and other Racket threads are not scheduled during the call to proc. A garbage collection may occur.

void |  | Sinitframe | ( | iptr num_args)

void |  | Sput_arg | ( | iptr i,
|  |  |  | ptr arg)

ptr |  | Scall | ( | ptr proc,
|  |  |  | iptr num_args)

Similar to Scall0, but these functions are used in sequence to apply a Chez Scheme procedure to an arbitrary number of arguments. First, Sinitframe is called with the number of arguments. Then, each argument is installed with Sput_arg, where the i argument indicates the argumenrt position and arg is the argument value. Finally, Scall is called with the procedure and the number of arguments (which must match the number provided to Sinitframe).
top ← prev up next →