Defines the constants, data structures and function prototypes used by the Workload Manager (WLM) Application Programming Interface (API) subroutines.
The wlm.h file defines the wlm_args, wlm_assign, wlm_info, and wlm_bio_class_info_t and wlm_bio_dev_info_t structures. These structures are used by the WLM API functions in the libwlm.a library.
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:
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.
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.
The main structure in the wlm_init_class_definition subroutine is the class description, struct class_descr, with the following fields:
The resource types are defined as WLM_RES_CPU, WLM_RES_MEM and WLM_RES_BIO. A value of 0 specifies type WLM_RES_CPU, 1 specifies type WLM_RES_MEM, and 2 specifies type WLM_RES_BIO. Each value represents the index in the array of the element corresponding to the type of resource.
The default when this attribute is not specified is that no user 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.
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.
In addition to the class description fields, the class_definition structure adds two more fields:
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:
| wa_versflags | Specifies the 4 high-order bits containing a version number. This
version number is 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 the version number WLM_VERSION. The flag WLM_MUTE can be used to suppress the output of error messages from the WLM library on stderr. |
| wa_pids | Specifies the address of an array containing the process identifiers (PIDs) of the processes to be manually assigned |
| wa_pid_count | Specifies the number of PIDs in the array above |
| wa_pgids | Specifies the address of an array containing the process group IDs (PGIDs) of the process groups to be manually assigned |
| wa_pgid_count | Specifies the number of PGIDs in the array above |
| wa_classname | Specifies the full name of the superclass or the subclass of the class to which you want to manually assign processes |
The wlm_info structure is used to extract information about the
current configuration parameters and current resource utilization of the
active classes using the wlm_get_info subroutine. The
wlm_info structure contains the following fields:
| i_descr | Specifies the class description of type struct class_descr |
| i_regul | Specifies the per-resource-type array of structures, which are of the
type struct wlm_regul, containing the following fields:
The indexes into the array of the various resources are defined as WLM_RES_CPU, WLM_RES_MEM and WLM_RES_BIO. |
| i_class_id | Specifies the class identifier (index of the class in the kernel class_control_block (ccb) table) |
| i_cl_pri | Specifies the priority delta applied to the threads in the class for CPU regulation |
| i_cl_inuse | Specifies the current number of processes in the class |
| i_cl_npages | Specifies the number of memory pages currently allocated to the class |
| i_cl_mem_hwm | Specifies the maximum number of resident memory pages this class had since its creation (memory high water mark) |
| i_cl_change_level | Specifies the number of increments each time a change in the current WLM configuration occurs. This field is used by the WLM monitoring tools. |
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_bio_class_info_t structure is used to gather I/O statistics per class and per device. The wlm_bio_class_info_t structure contains the following fields:
| wbc_dev | Specifies the device identifier (dev_t) |
| wbc_cid | Specifies the class identifier (index of the class in the kernel class_control_block table). Connecting the class ID and the class name can be performed by using the wlm_get_info subroutine. This subroutine returns the class name (in the i_descr field) and the class ID (in the i_class_id field) in the wlm_info structure. |
| wbc_regul | Specifies a structure of type struct wlm_regul, which contains
for the given class and device the following disk I/O statistics:
|
| wbc_delay | Specifies in milliseconds the delay imposed on the I/Os of the processes in the class to the device. This delay is intended to limit utilization by class when it is consuming more than its entitled share. |
The wlm_bio_dev_info_t structure is used to gather the global
statistics for a given device, taking into account all I/Os to and from the
device by all the classes accessing the device. This structure contains
the following fields:
| wbd_dev | Specifies the device identifier (dev_t) |
| wbd_active_cntrl | Specifies the number of classes actively accessing the device |
| wbd_in_queue | Specifies the number of requests in the device queue |
| wbd_last | Specifies the device statistics for IOs that occurred during the last
second.
This field is an array of integer values. The following symbolic values defined in the wlm.h file describe each index in the array:
|
| wbd_max | Contains the maximum values observed since the device was first used (after WLM was started) for all the entries of the array being described. For instance, the wbd_max field could contain the maximum number of blocks actually read from the device in one second since the device was first accessed. |
| wbd_av | Contains the average values for all the entries in the array, such as the average number of requests in the device queue |
| wbd_total | Specifies an array of 64-bit integers. This array is parallel to the arrays that, for every entry, contain the total of all the values measured every second since the device was first accessed. For instance, the value could represent the total number of blocks written to the device since the device was first accessed. |
The various WLM API subroutines may return one or several of the following
error codes:
| WLM_BADVERS | Bad version number passed in the versflags field |
| WLM_NOTINITED | No prior call to the wlm_initialize subroutine |
| WLM_ALREADYINIT | A call to the wlm_initialize subroutine has already been made |
| WLM_OPENERR | A file could not be opened |
| WLM_CREATERR | A file could not be created |
| WLM_MKDIRERR | A directory could not be created |
| WLM_WRITERR | An attempt to write to a file did not succeed |
| WLM_REMERR | An attempt to remove a file did not succeed |
| WLM_RENAMERR | An attempt to rename a file did not succeed |
| WLM_SYMLERR | An attempt to create a symbolic link did not succeed |
| WLM_NOMEM | Not enough memory |
| WLM_NOCLASS | The specified class does not exist |
| WLM_RNOCLASS | A class specified in the rules file does not exist |
| WLM_EXISTS | The specified class already exists |
| WLM_MAXCLASSES | The maximum number of classes has been reached |
| WLM_RMPREDEF | Predefined classes (such as Default and System) cannot be removed |
| WLM_NOSUBS | The target superclass has no subclasses |
| WLM_HASSUBS | The target superclass has subclasses |
| WLM_SHAREDSUB | Shared superclass cannot have subclasses |
| WLM_SHAREDLIM | Shared class can have shares and limits set only for memory |
| WLM_BADDEFSHR | Default shares value that is specified in the shares file is invalid |
| WLM_BADDEFLIM | Default limits value that is specified in the limits file is invalid |
| WLM_BADLIMFMT | Value specified for minimum or maximum resource limit is invalid |
| WLM_BADSHRFMT | Value specified for resource shares is invalid |
| WLM_BADTIER | Tier values must be between 0 and 9 |
| WLM_BADSHARES | Shares values must be between 1 and 65535 |
| WLM_BADMIN | Minimum resource limits values must be between 0 and 100 |
| WLM_BADSMAX | The soft maximum limit values must be between 1 and 100 |
| WLM_BADHMAX | The hard maximum limit values must be between 1 and 100 |
| WLM_BADCNAME | Class names must be alphanumeric |
| WLM_TOOLONG | The specified class name is too long |
| WLM_MINSMAX | The minimum limit cannot be greater than the soft maximum limit |
| WLM_SMAXHMAX | The soft maximum limit cannot be greater than the hard maximum limit |
| WLM_SUMMINS | The sum that the minimum limits for a given resource and a given tier cannot exceed 100% |
| WLM_BADINHER | The value specified for the class inheritance attribute is invalid |
| WLM_LOADERR | A class cannot be loaded into the kernel |
| WLM_RULESERR | The assignment rules table cannot be loaded into the kernel |
| WLM_SETERR | The WLM state transition requested is illegal |
| WLM_QUERYERR | Cannot query WLM state |
| WLM_MANYRULES | Too many assignment rules |
| WLM_MANYITEMS | Too many items in an assignment rule |
| WLM_RULERR | An assignment rule has an invalid format |
| WLM_BADLIST | The process attribute list of an assignment rules is invalid |
| WLM_BADUSR | The specified user ID is not valid on the system |
| WLM_BADRUSR | A user name specified in the rules file is invalid on the system |
| WLM_BADUID | The specified user ID is not valid on the system |
| WLM_BADGRP | The specified group ID is not valid on the system |
| WLM_BADRGRP | A group name specified in the rules file is invalid on the system |
| WLM_BADGID | The specified group ID is not valid on the system |
| WLM_BADTAG | An invalid tag is specified in a rule |
| WLM_NOSHRRULE | Cannot specify rule for Shared class |
| WLM_NOWILDCRD | Wildcards not allowed in this field |
| WLM_STATERR | One or more file name(s) specified in the application field of an assignment rule could not be accessed. The corresponding name(s) are ignored (warning) |
| WLM_EMPTYRULE | None of the file names specified in the application field of an assignment rule could be accessed. The rule is ignored (warning). |
| WLM_RUNERR | The WLM library was not able to execute a command needed for the specific function. This is not an application error, but most likely a system administration problem. The commands used by the library are basic operating system commands such as the lsuser, lsgroup, echo, and grep commands. |
This file is part of Base Operating System (BOS) Runtime.
The wlm_init_class_definition subroutine, wlm_assign subroutine, wlm_get_info subroutine.
Chapter 13. Workload Management in AIX 5L Version 5.1 System Management Concepts: Operating System and Devices