API Wrap

[ ruby-oci8 2.0 only ]

'ext/oci8/apiwrap.yml' is used for the following three purposes.

1. Use non-blocking API easily.
2. Check function existence at run-time.
3. Trace function calls.

ruby 1.8's thread model is green. If one thread is blocked in a C extension library, all threads are also blocked. ruby 1.9's thread model is native. But ruby threads don't run parallel. When one thread do a long operation in C, it should release a global VM lock. The ways to prevent a C library from blocking ruby itself are quite different in ruby 1.8 and 1.9. But apiwrap make it easy.

If you use a OCI function OCIFooBar() and it needs more than one server round trip, you need to add the function name with the following information to apiwrap.yml.

• oracle version in which the function was added.
• :remote: true
• arguments

If :remote: is true, apiwrap.rb makes a function prototype of OCIFooBar_nb(). The only difference between OCIFooBar() and OCIFooBar_nb() is that "oci8_svcctx_t *svcctx" is added as a first argument of the latter. What you need to do is to use OCIFooBar_nb() instead of OCIFooBar() and pass oci8_svcctx_t* as the first argument.

ruby-oci8 2.0 supports Oracle 8.0 or later. But you can use newly added functions in later Oracle versions by one compiled binary oci8lib.so. This is useful when we make a compiled Windows package. We need to make packages depends on Oracle versions without this feature,

If you use a OCI function OCIFooBar which was added in Oracle X.Y.Z, you need to add the function name with the following information to apiwrap.yml.

• :version: XYZ (without dots. 8.1.7 -> 817, 10.1.0 -> 1010, etc)
• :remote: true or false
• arguments

In C code:

 if remote is true:
     if (have_OCIFooBar_nb) {
         can OCIFooBar_nb
     } else {
         don't use OCIFooBar_nb here
     }
 if remote is false:
     if (have_OCIFooBar) {
         can OCIFooBar
     } else {
         don't use OCIFooBar here
     }

have_OCIFooBar is a variable if runtime API-check is enabled. It is a macro if runtime check is disabled.

We have not implemented yet. All OCI function calls can be logged by this feature. It will be useful when debugging.