wlm.h File

Purpose

Defines the constants, data structures and function prototypes used by the Workload Manager (WLM) Application Programming Interface (API) subroutines.

Description

The wlm.h file defines the wlm_args, wlm_assign, wlm_info, wlm_bio_class_info_t, and wlm_bio_dev_info_t, and wlm_proc_info structures. These structures are used by the WLM API functions in the libwlm.a library.

The wlm_args Structure

The wlm_args structure is used to pass class information to WLM when using the API functions to create, modify or delete a class. The wlm_args structure contains the following fields:

versflags

Specifies the 4 high-order bits that contain a version number used by the API to maintain binary compatibility if the data structures are ever modified. The rest of the integer is used to pass flags to the subroutines when needed.

This field should be initialized with a logical OR operation between the version number WLM_VERSION and whatever flags are needed by the target subroutine. One flag common to all the API calls is WLM_MUTE, which is used to suppress the output of error messages from the WLM library to STDERR.

confdir

Specifies a null-terminated string. This field must be initialized with the name of the WLM configuration to which the target subroutine applies (when applicable, depending on the particular one).

Alternatively, this field can be set to a null string (\0). The null string indicates that the class addition or modification is to be applied only to the WLM kernel data, not to the class description files.

class

This field is a structure of type struct class_definition that contains all the information pertaining to the superclass or subclass that is needed by the target subroutine. The fields in this structure can be initialized by a call to the wlm_init_class_definition subroutine so that you only need to initialize the fields you wish to modify.

The main structure in the wlm_init_class_definition subroutine is the class description, struct class_descr, with the following fields:

res

Specifies an array of type struct wlm_bounds that contains the following fields for each resource type and for each total limit:

iopriority

Specifies the priority for I/O requests that are issued by the threads that are classified to the class. This priority is used to prioritize I/O buffers at the device level. Valid I/O priorities range from 0 through 15.

min

Specifies the minimum value, which is between 0 (the default) and 100 (unused for total limits).

shares

Specifies the shares number, which is a value between 1 and 65535. The value -1 (default) indicates that the given resource is not managed by WLM for the class (unused for total limits).

wlmu

The union which contains the softmax (for all resources but total limits) and unit (for total limits only) fields:

softmax

Specifies the soft maximum limit, which is a value between 0 and 100 (default). The value must be greater than or equal to the value of the min field.

unit

A string (3 characters maximum) that specifies the units that apply to the hardmax value for total limits. To let the units remain undefined, set the softmax field to WLM_UNIT_UNDEF. For WLM_RES_TOTALCONNECT and WLM_RES_TOTALCPU, the default unit is "s" (seconds) and other values are "m" (minutes), "h" (hours), "d" (days), and "w" (weeks). For WLM_RES_TOTALDISKIO, the default unit is "KB" (kilobytes) and other values are "MB" (megabytes), "GB" (gigabytes), "TB" (terabytes), "PB" (petabytes), "EB" (exabytes). The other total limits do not have units. For WLM_RES_TOTALVMEM and WLM_RES_PROCVMEM, set the unit to "MB", "GB", and "TB".

hardmax

For all resources but total limits. Specifies the hard maximum limit, which is a value between 0 and 100 (default). The value must be greater than or equal to each of the values of the min and softmax fields. For total limits, this parameter specifies their value, possibly along with the unit field. If the user does not specify a units value, the default units value is used. However, the user can specify a units value other than the default. The default (total limit unspecified) is WLM_HARDMAX_UNDEF.

The resource types are defined as WLM_RES_CPU, WLM_RES_MEM, WLM_RES_BIO, and total limits are defined as WLM_RES_TOTALCPU (total CPU time for a process), WLM_RES_TOTALDISKIO (total disk IOs for a process), WLM_RES_TOTALCONNECT (total Connection time), WLM_RES_TOTALPROC (total number of processes), WLM_RES_TOTALTHRD (total number of Threads), WLM_RES_TOTALLOGIN (total number of login sessions), WLM_RES_TOTALVMEM (total virtual memory usage for a class) and WLM_RES_PROCVMEM (total virtual memory usage for a process). Each value represents the index in the array of the element, corresponding to the type of resource or total limit.

tier

Specifies the tier number for the class, which is a value between 0 (default) and 9

inheritance

Specifies how a new process is classified. A value of 0 (the default) indicates that a new process should be classified using the class assignment rules when calling the exec subroutine. A value of 1 indicates that the process inherits the class assignment from its parent process.

localshm

Indicates whether memory segments in this class remain local to the class (value 1) or if they go to the Shared class (value 0, the default), when accessed by a process belonging to another class.

assign_uid

Specifies the user ID of the user allowed to manually assign processes to the class. The value must be a valid user ID.

The default when this attribute is not specified is that no user is authorized (WLM_NOGUID).

assign_gid

Specifies the group ID of the users allowed to manually assign processes to the class. The value must be a valid group ID. The value must be a valid group ID. The default when this attribute is not specified is that no group is authorized (WLM_NOGUID).

If both the assign_uid and assign_gid fields are the default value, only the root user can assign processes to the class.

admin_uid

Specifies the user ID of the user allowed to administer the subclasses of the superclass (this attribute is valid only for superclasses)

admin_gid

Specifies the group ID of the users allowed to administer the subclasses of the superclass (this attribute is valid only for superclasses)

If both the admin_uid and admin_gid fields are left to their default value (WLM_NOGUID), only the root user can administer the subclasses of this superclass.

name

Specifies the null-terminated full name of the class. The value must be in the format super_name for a superclass and super_name.sub_name for a subclass. The superclass name and subclass name are limited to 16 characters each. This field has no default value.

In addition to the class description fields, the class_definition structure adds two more fields:

rset_name

Specifies a null-terminated character string containing the name of the resource set (partition) that the class is restricted to, when applicable. The default is that the class can access all the resources on the system.

descr_field

Specifies a null-terminated character string containing the description text of the class. This field is optional and has no default.

delshm

Specifies whether to delete shared memory segments if the last process referencing the segment was killed due to a virtual memory limit. Valid values are "yes" and "no" (default).

vmenforce

Specifies whether the faulting process (value "proc", default) or all processes in a class (value "class") are killed when a virtual memory limit is reached.

The wlm_assign Structure

The wlm_assign structure is used to manually assign processes or groups of processes to a specified superclass or subclass using the wlm_assign subroutine. The wlm_assign structure contains the following fields:

The wlm_info Structure

The wlm_bio_class_info_t and wlm_bio_dev_info_t Structures

Two structures can be used to get the I/O statistics using the wlm_get_bio_stats subroutine, depending on whether the application wants per-class or per-device statistics.

The wlm_proc_info Structure

The wlm_proc_info structure is used to extract Workload Manager information about a process using the wlm_get_procinfo subroutine. The totalconnecttime, termtime, totalcputime, totaldiskio fields are only meaningful when the total process limits are enabled. The wlm_proc_info structure contains the following fields:

version

This field should be initialized with WLM_VERSION.

wlmflags

Specifies some Workload Manager properties of the process, such as process with a rset SWLMRSET or as tag inheritance on fork SWLMTAGINHERITFORK or on exec SWLMTAGINHERITEXEC.

totalconnecttime

Specifies the 64-bit number that represents the amount of time (in seconds) for which the login session has been active.

totalvmem

Specifies the total amount of virtual memory used by the process in MBs.

termtime

Specifies the 64-bit number that represents the time (in seconds from 1970) when the process has been requested to terminate.

totalcputime

Specifies the 64-bit number that represents the amount of the CPU consumption (in microseconds) of the process.

totaldiskio

Specifies the 64-bit number that represents the amount of IO (in 512 bytes blocks) the process has run.

classname

Specifies the full name of the superclass or the subclass in which the process is classified.

tag

Specifies the character string associated with the process, if any ( see wlm_set_tag subroutine).

Error Codes