add (incomplete) documentation for the state of C ext support

Author: timfel

docs/README.cext

@@ -0,0 +1,142 @@
+## JRuby implementation of Ruby C extensions API.
+
+This document explains the state of C extensions on JRuby. This is
+meant to become an exhaustive listing of the restrictions in the C API
+layer, their reasons, and how to work around them.
+
+We also provide code examples for some workarounds at the end of this
+document.
+
+If more restrictions are found, or you have code examples, please feel
+free to add them.
+
+### Objectives
+
+Provide a highly compatible implementation of C extensions on
+JRuby. The goal here is not performance, but compatibility. We do not
+recommend running Ruby C extensions in production, at least not for a
+longer period of time, and we probably never will. The idea here is
+that if you're transitioning to JRuby, you can run your C extensions
+until you find something more suitable. The focus is also very clearly
+on Gems that have no JRuby specific version available. The C API is
+implemented as a JNI plugin to the JVM.
+
+### Restrictions
+
+#### Runtime
+
+JRuby supports multiple "Runtimes" in a single process. Because you
+can only load a dynamic/shared library into the JVM once, and we
+cannot be sure whether a C extension is thread-safe, so we disallow
+loading C extensions in more than one runtime. To work around this,
+you may disable JRuby's in-process execution (default from 1.6.5
+onwards).
+
+#### Strings
+
+* **RSTRING_PTR(VALUE)**
+
+    *Problem:* In order to support direct manipulaton of C array
+     backed strings, whenever you call this macro, the object
+     referenced by VALUE is added to a synchronization list, and
+     whenever you transition between C and Java land, the contents of
+     the Java and C string are copied back and forth, adding a
+     potentially significant overhead.  The lifetime of the C memory
+     referenced by the result of RSTRING_PTR is the same as the
+     garbage collection lifetime of the corresponding String object,
+     so it will only go off the synchronization list if the associated
+     object is collected.
+
+    *Workaround:* To change bytes in a String object, use one of
+
+	void rb_str_update(VALUE str, long beg, long len, VALUE val);
+	VALUE rb_str_buf_append(VALUE str, VALUE val);
+	VALUE rb_str_buf_cat(VALUE str, const char* bytes, long len);
+	VALUE rb_str_buf_cat2(VALUE str, const char* cstring);
+	VALUE rb_str_append(VALUE str, VALUE arg);
+
+#### Arrays
+
+* **RARRAY_PTR**
+
+    *Problem:* The same runtime overhead implications as for RSTRING_PTR apply.
+
+    *Workaround:* To access elements of an Array, use rb_ary_entry or
+    rb_ary_store which are also available in MagLev and Rubinius.
+
+#### IO
+
+* **rb_io_wait_readable, rb_io_wait_writable, rb_io_check_readable, rb_io_check_writable, rb_io_check_closed, GetOpenFile**
+    
+    *Problem:* Mixing native file descriptors with JVM fds doesn't
+     work very well. Sometimes, things will work just fine, but more
+     often than not, these functions will simply fail.
+
+    *Workaround:* Upcall to Ruby for dealing with IO and files.
+
+#### Hash
+
+* **rb_iterate_each_pair**, **rb_iterate**, **rb_each**
+
+    *Problem:* Only supports iteration on Array arguments for now
+
+    *Workaround:* You can coerce you're Hash into an array of pairs
+     before iterating.
+
+* **RHASH**, **RHASH_TBL**
+
+    *Problem:* Like on MagLev and Rubinius, these macros aren't supported.
+
+#### Threads
+
+* **thread_critical**
+
+    *Problem:* Not supported, setting this to `true` is ignored
+
+#### Globals and GC
+
+* **Object lifetime**
+
+    *Problem:* C-references aren't kept alive/valid after returning
+    from C extension code.
+
+    Each call from Ruby into a C extension initializes a list known to
+    the garbage collector that is kept alive for the duration of that
+    entry into a C extension. This list is dereferenced when returning
+    from C back to Ruby.
+
+    *Workaround:* For a newly created object to stay alive after
+    returning from C to Ruby it must have been stored as the value of
+    a Ruby global variable, Ruby constant, or stored into an instance
+    variable of some other object reachable from top level Ruby state,
+    or be reachable from the VALUE returned from C back to Ruby.
+
+#### Numerics
+
+* **rb_num2ulong**
+  
+  *Problem:* Java longs are of a different size than whatever the
+   native long size may be on the machine. This can be observed in the
+   spec failure "rb_num2ulong converts -1 to an unsigned number" in
+   the Ruby specs.
+
+  *Workaround:* None.
+
+### Bugs and status of rubyspecs (as of 30 Sep 2011)
+
+For the rubyspecs in optional/capi/ , the following specs are skipped
+and are not supported
+
+ * rb_define_hooked_variable
+ * rb_define_variable
+ * rb_protect_inspect
+ * rb_inspecting_p
+ * rb_exec_recursive
+
+The following functions have known bugs that we will try to fix
+
+ * rb_class_new fails to throw an error when passed a singleton class as superclass
+ * rb_rescue has some spec failures
+ * rb_thread_select fails to detect an fd that's ready to read
+ * rb_str_buf_* sometimes fails to synchronize the C buffer correctly
+