[GR-13433] Update the compatibility document for C extensions.

PullRequest: truffleruby/547

Author: eregon

doc/user/compatibility.md

@@ -168,28 +168,13 @@ disabled where we dynamically detect that they probably won't be used. See the
 
 ## C Extension Compatibility
 
-#### Storing Ruby objects in native structures and arrays
+#### `VALUE` is a pointer
 
-You cannot store a Ruby object in a structure or array that has been natively
-allocated, such as on the stack, or in a heap-allocated structure or array.
-
-Simple local variables of type `VALUE`, and locals arrays that are defined such
-as `VALUE array[n]` are an exception and are supported, provided their address
-is not taken and passed to a function that is not inlined.
-
-`void *rb_tr_handle_for_managed(VALUE managed)` and `VALUE
-rb_tr_managed_from_handle(void *native)` may help you work around this
-limitation. Use `void* rb_tr_handle_for_managed_leaking(VALUE managed)` if you
-don't yet know where to put a corresponding call to `void
-*rb_tr_release_handle(void *native)`. Use `VALUE
-rb_tr_managed_from_handle_or_null(void *native)` if the handle may be `NULL`.
-
-#### Mixing native and managed in C global variables
-
-C global variables can contain native data or they can contain managed data,
-but they cannot contain both in the same program run. If you have a global you
-assign `NULL` to (`NULL` being just `0` and so a native address) you cannot
-then assign managed data to this variable.
+In TruffleRuby `VALUE` is a pointer type (`void *`) rather than a
+integer type (`long`). This means that `switch` statements cannot be
+done using a raw `VALUE` as they can with MRI. You can normally
+replace any `switch` statement with `if` statements with little
+difficulty if required.
 
 #### Identifiers may be macros or functions
 
@@ -200,34 +185,18 @@ address of it, assigning to a function pointer variable and using defined() to
 check if a macro exists). These issues should all be considered bugs and be
 fixed, please report these cases.
 
-#### Variadic functions
-
-Variadic arguments of type `VALUE` that hold Ruby objects can be used, but they
-cannot be accessed with `va_start` etc. You can use
-`void *polyglot_get_arg(int i)` instead.
-
-#### Pointers to `VALUE` locals and variadic functions
-
-Pointers to local variables that have the type `VALUE` and hold Ruby objects can
-only be passed as function arguments if the function is inlined. LLVM will never
-inline variadic functions so pointers to local variables that hold Ruby objects
-cannot be passed as variadic arguments.
-
-`rb_scan_args` is an exception and is supported.
-
 #### `rb_scan_args`
 
 `rb_scan_args` only supports up to ten pointers.
 
 #### `RDATA`
 
-The `mark` function of `RDATA` and `RTYPEDDATA` is never called.
-
-#### Ruby objects and truthiness in C
-
-All Ruby objects are truthy in C, except for `Qfalse`, the `Integer` value `0`,
-and the `Float` value `0.0`. The last two are incompatible with MRI, which would
-also see these values as truthy.
+The `mark` function of `RDATA` and `RTYPEDDATA` is not called during
+garbage collection. Instead we simulate this by caching information
+about objects as they are assigned to structs, and periodically run
+all mark functions when the cache has become full to represent those
+object relationships in a way that the our garbage collector will
+understand. The process should behave identically to MRI.
 
 ## Compatibility with JRuby