+/**
+ * gidispatch_set_retained_registry:
+ * @regi: Function to call whenever the Glk library assumes ownership of an
+ * array.
+ * @unregi: Function to call whenever the Glk library releases ownership of an
+ * array.
+ *
+ * A few Glk functions take an array and hold onto it. The memory is
+ * <quote>owned</quote> by the library until some future Glk call releases it.
+ * While the library retains the array, your program should not read, write,
+ * move, or deallocate it. When the library releases it, the contents are in
+ * their final form, and you can copy them out (if appropriate) and dispose of
+ * the memory as you wish.
+ *
+ * To allow this, the library implements gidispatch_set_retained_registry().
+ *
+ * Again, you pass in two function pointers:
+ * |[
+ * gidispatch_rock_t my_vm_reg_array(void *array, glui32 len, char *typecode);
+ * void my_vm_unreg_array(void *array, glui32 len, char *typecode, gidispatch_rock_t objrock);
+ * ]|
+ *
+ * Whenever a Glk function retains an array, it will call
+ * <function>my_vm_reg_array()</function>. This occurs only if you
+ * pass an array to an argument with the <code>"#!"</code> prefix.
+ *
+ * <note><para>
+ * But not in every such case. Wait for the
+ * <function>my_vm_reg_array()</function> call to confirm it.
+ * </para></note>
+ *
+ * The library passes the array and its length, exactly as you put them in the
+ * #gluniversal_t array. It also passes the string which describes the argument.
+ *
+ * <note><para>
+ * Currently, the only calls that retain arrays are glk_request_line_event(),
+ * glk_stream_open_memory(), glk_request_line_event_uni(), and
+ * glk_stream_open_memory_uni(). The first two of these use arrays of
+ * characters, so the string is <code>"&+#!Cn"</code>. The latter two use
+ * arrays of #glui32, so the string is <code>"&+#!Iu"</code>.
+ * </para></note>
+ *
+ * You can return any value in the #gidispatch_rock_t object; the library will
+ * stash this away with the array.
+ *
+ * When a Glk function releases a retained array, it will call
+ * <function>my_vm_unreg_array()</function>. It passes back the same
+ * @array, @len, and @typecode parameters, as well as the #gidispatch_rock_t you
+ * returned from <function>my_vm_reg_array()</function>.
+ *
+ * With these callbacks, you can maintain a collection of retained arrays. You
+ * can use this to copy data from C arrays to your own data structures, or keep
+ * relocatable memory locked, or prevent a garbage-collection system from
+ * deallocating an array while Glk is writing to it.
+ */