Create a well-behaved routine

Because the CPU VP is used to execute all client requests, it is important that the code it executes be well-behaved; that is, all code must have the following attributes:
  • Preserve availability of the CPU VP

    The CPU VP performs system services and related tasks and executes code for UDRs. If a UDR issues a standard blocking I/O call in a CPU VP, then the VP must wait for the I/O to complete and cannot attend to other threads and administrative tasks. The time spent waiting adversely affects the overall performance of the system. DataBlade® API I/O functions enable the CPU VP to process the I/O asynchronously and do not block the CPU VP.

    The benefit of releasing the CPU VP so that it can execute other threads outweighs the overhead involved in saving the current thread state and switching to another thread. Each thread will explicitly yield the CPU VP in a timely manner (at least every 1/10 of a second).

  • Be process safe

    Well-behaved code must be able to migrate among processes without loss of essential information or changing the global VP state. C UDR code is process safe when all state information is entirely encapsulated within the arguments to each C function and within the scope of the function itself. UDRs must not use global variables or system calls that change the process state.

Code that is provided to execute within SQL statements (such as built-in SQL functions) is well-behaved. However, does not have control over the code you write in your C UDR. A C UDR must be well-behaved to execute in the CPU VP. As a UDR developer, you must ensure that your C UDR adheres to the safe-code requirements in the following table.

Table 1. Safe-code requirements for a well-behaved UDR
Safe-code requirement Coding rule Possible workarounds
Preserve availability. Yield the CPU VP in a timely manner (at least every 1/10 of a second). To execute in the CPU VP, use mi_yield() to explicitly yield the CPU VP during resource-intensive processing.

Otherwise, execute in a user-defined VP class.
Preserve availability. Do not use blocking I/O calls. Execute in a yielding user-defined VP class.
Preserve availability. Never change the working directory. None
Be process safe. No heap-memory allocation To execute in the CPU VP, use the DataBlade API memory-management functions.
Be process safe. No modification of global or static data To execute in the CPU VP, use the MI_FPARAM structure if you need to preserve state information. If necessary, global or static data can be read, as long as it is not updated.

Otherwise, execute in a nonyielding user-defined VP class or a single-instance user-defined VP.
Be process safe. No modification of the global state of the virtual processor A C UDR that modifies the global VP state cannot execute safely in any VP.

If modification of this data is essential to the application, execute the C UDR in a nonyielding user-defined VP class or a user-defined VP class that has only one VP defined.
Avoid unsafe operating-system calls. Do not use any system calls that might impair availability or allocate local resources. If use of such system calls is essential to the application, execute the C UDR in a nonyielding user-defined VP class and a single-instance VP and then change back.

If a UDR does not follow the safe-code requirements in Safe-code requirements for a well-behaved UDR , it is called an ill-behaved routine. An ill-behaved routine cannot safely execute in the CPU VP. Execution of an ill-behaved routine in the CPU VP can cause serious interference with the operation of the database server. In addition, the UDR itself might not produce correct results.

If your C UDR has one of the ill-behaved traits in Safe-code requirements for a well-behaved UDR , follow the suggestions in the Possible Workarounds column. The following sections describe more fully the safe-code requirements for a well-behaved C UDR.