On this page:
Inside:   Racket C API

Inside: Racket C API🔗

Matthew Flatt

The Racket runtime system is responsible for the implementation of primitive datatypes such as numbers and strings, the macro expansion and compilation of Racket from source, the allocation and reclamation of memory used during evaluation, and the scheduling of concurrent threads and parallel tasks.

This manual describes the C interface of Racket’s runtime system, which varies depending on the implementation of Racket (see Racket Virtual Machine Implementations): the CS implementation of Racket has one interface, while the BC (3m and CGC) implementation of Racket has another.

The C interface is relevant to some degree when interacting with foreign libraries as described in The Racket Foreign Interface. Even though interactions with foreign code are constructed in pure Racket using the ffi/unsafe module, many details of representations, memory management, and concurrency are described here. This manual also describes embedding the Racket run-time system in larger programs and extending Racket directly with C-implemented libraries.

    I Inside Racket CS

      1 Overview (CS)

        1.1 “S” versus “Racket”

        1.2 Racket CS Memory Management

        1.3 Racket CS and Places

        1.4 Racket CS and Threads

        1.5 Racket CS Integers

      2 Embedding into a Program (CS)

      3 Values and Types (CS)

        3.1 Global Constants

        3.2 Value Functions

      4 Calling Procedures (CS)

      5 Starting and Declaring Initial Modules (CS)

        5.1 Boot and Configuration

        5.2 Loading Racket Modules

        5.3 Startup Path Helpers

      6 Evaluation and Running Modules (CS)

      7 Managing OS-Level Threads (CS)

    II Inside Racket BC (3m and CGC)

      8 Overview (BC)

        8.1 “Scheme” versus “Racket”

        8.2 CGC versus 3m

        8.3 Embedding and Extending Racket

        8.4 Racket BC and Places

        8.5 Racket BC and Threads

        8.6 Racket BC, Unicode, Characters, and Strings

        8.7 Racket BC Integers

      9 Embedding into a Program (BC)

        9.1 CGC Embedding

        9.2 3m Embedding

        9.3 Flags and Hooks

      10 Writing Racket Extensions (BC)

        10.1 CGC Extensions

        10.2 3m Extensions

        10.3 Declaring a Module in an Extension

      11 Values and Types (BC)

        11.1 Standard Types

        11.2 Global Constants

        11.3 Strings

        11.4 Value Functions

      12 Memory Allocation (BC)

        12.1 Cooperating with 3m

          12.1.1 Tagged Objects

          12.1.2 Local Pointers

          12.1.3 Local Pointers and raco ctool --xform

          12.1.4 Guiding raco ctool --xform

          12.1.5 Places and Garbage Collector Instances

        12.2 Memory Functions

      13 Namespaces and Modules (BC)

      14 Procedures (BC)

      15 Evaluation (BC)

        15.1 Top-level Evaluation Functions

        15.2 Tail Evaluation

        15.3 Multiple Values

        15.4 Evaluation Functions

      16 Exceptions and Escape Continuations (BC)

        16.1 Temporarily Catching Error Escapes

        16.2 Enabling and Disabling Breaks

        16.3 Exception Functions

      17 Threads (BC)

        17.1 Integration with Threads

        17.2 Allowing Thread Switches

        17.3 Blocking the Current Thread

        17.4 Threads in Embedded Racket with Event Loops

          17.4.1 Callbacks for Blocked Threads

        17.5 Sleeping by Embedded Racket

        17.6 Thread Functions

      18 Parameterizations (BC)

      19 Continuation Marks (BC)

      20 String Encodings (BC)

      21 Bignums, Rationals, and Complex Numbers (BC)

      22 Ports and the Filesystem (BC)

      23 Structures (BC)

      24 Security Guards (BC)

      25 Custodians (BC)

      26 Subprocesses (BC)

      27 Miscellaneous Utilities (BC)

    III Appendices

      28 Building Racket from Source

      29 Cross-compiling Racket Sources for iOS

      30 Linking to DLLs on Windows

      31 Embedding Files in Executable Sections

        31.1 Accessing ELF Sections on Linux

        31.2 Accessing Mac OS Sections

        31.3 Accessing Windows Resources