# Ruby C-API

Rubinius provides a compatible Ruby (MRI) C-API for C-language extensions.
Since the Rubinius VM is written in C++, there are a number of things to
understand about how the C-API is implemented.

The following diagram shows the flow of types and values from Rubinius through
the C-API to C extensions.


                  +----------------------------------------------+
                  |                  Rubinius VM                 |
                  | +-------------------+  +-------------------+ |
                  | | builtin/array.cpp |  | builtin/array.hpp | |
                  | +-------------------+  +-------------------+ |
                  |  ...                    ...                  |
                  | +-------------------+  +-------------------+ |
                  | | other VM data     |  | other headers     | |
                  | | structures/values |  +-------------------+ |
                  | +-------------------+                        |
                  +----------------------------------------------+
                - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Types and     +----------------------------------------------+
    Values flow   |                  Ruby C-API                  |
        |         | +------------------------------------------+ |
        |         | |                 ruby.h                   | |
        v         | +------------------------------------------+ |
                  | +-------------------+ +----------------------+
                  | | capi/capi.hpp     | |
                  | +-------------------+ |  +-------------------+
                  |                       |  |    C extension    |
                  | +-------------------+ |  |                   |
                  | | capi/capi.cpp     | |  |                   |
                  | +-------------------+ |  +-------------------+
                  | +-------------------+ |
                  | | capi/array.cpp    | |
                  | +-------------------+ | <-- The C-extension
                  |  ...                  |     link boundary
                  +-----------------------+


The line between the Rubinius VM and the C-API is dashed because it is a
logical division. The C-API runs in the same application space as the rest of
the VM.

This is an important point to understand. The implementation of the C-API is
using the types and values of C++ and the rest of the VM. However, in the
C-API all objects that a C extension will use are referenced indirectly by
handles.

The C-API functions work internally with regular VM objects (like Array and
Object), but only pass types of VALUE or ID to C extensions. See
vm/builtin/nativemethod.hpp for Handles. (TODO: explain this better)

The C-API files

    ruby.h - provides prototypes for all C functions that need to be available
    to C extensions. Also exposes some C-API implemenation functions that are
    needed for macros in the C-API. Redefines the values of Qfalse, Qtrue,
    Qnil, and Qundef to be handles for the C extensions.

    capi.hpp - prototypes and templates used in the C-API implementation.

    capi.cpp - definitions for C-API implementation functions.

    *.cpp - implementations for rb_xxx functions organized by the Ruby class
    they operate on.
