Obtaining VP-Environment Information

Home | Previous Page | Next Page Creating User-Defined Routines > Writing a User-Defined Routine > Controlling the VP Environment >

Obtaining VP-Environment Information

By default, the routine manager executes a C UDR in a CPU VP class, which is a yielding VP class. However, execution on the CPU VP implies that the UDR is well-behaved. (For more information, see Creating a Well-Behaved Routine.) If your UDR is not well-behaved, you can specify that the routine manager execute the UDR in a user-defined VP class. However, a user-defined VP class imposes limitations on the tasks that the UDR can perform. If these limitations are too restrictive for your UDR, the UDR can dynamically obtain information about its VP environment and make decisions about whether to change it.

Warning:

The need to examine and possibly change the VP environment should only be done in special cases. For the most efficient execution, a C UDR should be well-behaved and thereby execute safely in the CPU VP. Ill-behaved routines can usually execute in a user-defined VP class without changing the VP environment.

From within a C UDR, you can obtain the following kinds of information about the VP environment:

Information about the current VP
Information about the VP class to which the current VP belongs

If a UDR can identify its VP environment, it can sometimes take care of its own migratory needs.

Identifying the Current VP

A VP that is currently performing some task is called an active VP. The database server assigns a unique integer, called the VP identifier, to each active VP. The onstat -g glo command displays the VP identifier in the first column of the output it generates (column with the heading "vp"). For example, the onstat output in Figure 79 shows information for VPs whose VP identifiers range from 1 to 13.

The VP identifier uniquely identifies the running oninit process. You can use it as an identifier for named memory that stores information unique to that VP.

The active VP on which a UDR executes is the current VP for the UDR. To obtain the VP identifier of the current VP, use the mi_vpinfo_vpid( ) function. Once you have the VP identifier of the current VP, you can use the following functions to obtain additional information about the VP environment of the UDR.

VP-Environment Information	DataBlade API Function
VP-class identifier	mi_vpinfo_classid( )
Whether the current VP is part of a nonyielding VP class	mi_vpinfo_isnoyield( )

Identifying a VP Class

The database server assigns a unique integer, called the VP-class identifier, to each VP class, including:

System VP classes (such as CPU and AIO)
User-defined VP classes (which the VPCLASS configuration parameter defines)

You can obtain a VP-class identifier with either of following DataBlade API functions.

DataBlade API Function	VP-Class Identifier Returned
mi_vpinfo_classid( )	The VP-class identifier for the VP class of the current VP (the VP on which the current UDR is running)
mi_class_id( )	The VP-class identifier for a specified VP class

Once you have a VP-class identifier for an active VP, you can obtain the following information about the associated VP class.

VP-Class Information	DataBlade API Function
VP-class name	mi_class_name( )
Maximum number of VPs in the VP class	mi_class_maxvps( )
Number of active VPs in the VP class	mi_class_numvp( )