The single-instance user-defined VP

A single-instance user-defined VP class is a VP class that has only one VP. Therefore, it runs a C UDR in a way that gives the routine exclusive use of the entire VP class.

As with a nonyielding user-defined VP, a single-instance VP executes a C UDR serially. Therefore, the UDR does not need to yield. Because a single-instance VP class has only one VP, the thread that executes the UDR does not migrate to another VP.

Depending on your requirements for yielding, a single-instance user-defined VP can be regular or nonyielding. A regular single-instance user-defined VP can handle the use of malloc() and other local memory access. If it is nonyielding, the VP can deal with problems like modification of global variables.

CPU VP safe-code requirement	Required for single-instance user-defined VP?
Yields the CPU on a regular basis	Not required
Does not use blocking operating-system calls	Not required
Does not allocate local resources, including heap memory	Yes
Does not modify global or static data	Not required (for global changes accessed by a single instance of the UDR)
Does not modify other global process-state information	Not required (for global changes accessed by a single instance of the UDR)
Does not use restricted operating-system calls	Required for some calls

The main advantage of a single-instance user-defined VP class is that all instances of the UDR are guaranteed to run on the same VP (that is, on the same system process). Therefore, changes the UDR makes to the global information (global or static variables, or the global process state) are accessible across all instances of the UDR. A UDR might execute many times for a query, once for each row processed. With multiple VPs in a class, you cannot guarantee that all instances of a UDR execute on the same VP. Though execution for the first invocation might be on one VP, the execution for the next invocation might be on some other VP.

The only way to guarantee that all instances execute on one VP is to define a single-instance user-defined VP class. Therefore, a single-instance user-defined VP class is useful for a UDR that shares special information across multiple instances. Examples might be a special iterator function or a user-defined aggregate.

Tip: The DataBlade API supports the mi_udr_lock() function to explicitly lock a UDR to a VP. For more information, see Lock a routine instance to a VP.

For example, suppose you have a UDR that contains the following code fragment:

{
   static stat_var;
   static file_desc;
   mi_integer num_bytes_read;
   ...
   file_desc = mi_file_open(....);
   num_bytes_read = mi_file_read(file_desc ....);
   ...
}

If this UDR ran on a yielding user-defined VP, the thread might yield at the mi_file_read() call. Another thread might then execute this same code and change the value of file_desc. When the original thread returned, it would no longer be reading from the file it had opened. Instead, if you can assign this UDR to a nonyielding user-defined VP, the thread never yields and the value of file_desc cannot be changed by other threads.

The main disadvantage of a single-instance user-defined VP is that it removes concurrency of UDR execution. This loss of concurrency brings the following restrictions:

A single-instance user-defined VP is probably not a scalable solution.
All instances of the UDR that execute on a single-instance VP must compete for the same VP. You cannot increase the number of VPs in the single-instance class to improve performance.
A single-instance user-defined VP does not support execution of parallel UDRs.

Important: If your UDR needs to make changes to global information that is available across only a single invocation of the UDR, use a nonyielding user-defined VP to execute the UDR. For more information, see The nonyielding user-defined VP.

You must weigh these advantages and disadvantages carefully when choosing whether to use a single-instance user-defined VP class to execute your ill-behaved UDR. For more information, see Define a single-instance user-defined VP class.