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, 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 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, 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). Each value represents the index in the array of the element, corresponding to the type of resource or total limit.
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_nblogins | Specifies the current number of logins in the class. |
i_cl_nbthreads | Specifies the current number of threads 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 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:
The various WLM API subroutines may return one or several of the following error codes:
WLM_ALREADYINIT | A call to the wlm_initialize subroutine has already been made |
WLM_ATTERR | Attribute format error |
WLM_ATTGPATTR | Attribute Value Grouping not allowed in attributes |
WLM_ATTGPMISS | Cannot find Attribute Value Grouping definition |
WLM_ATTGPTOOLNG | Attribute Value Grouping too long |
WLM_BADATTAPP | Could not access file (application field of attributes) |
WLM_BADATTGP | Bad format for Attribute Value Grouping |
WLM_BADATTGRP | Unknown group in attributes |
WLM_BADATTTAG | Invalid tag in attributes |
WLM_BADATTTYP | Invalid process type in attributes |
WLM_BADATTUSR | Unknown user in attributes |
WLM_BADCLNAME | Bad class name |
WLM_BADCNAME | Class names must be alphanumeric |
WLM_BADCONFIG | Invalid configuration name |
WLM_BADDEFLIM | Default limits value that is specified in the limits file is invalid |
WLM_BADDEFSHR | Default shares value that is specified in the shares file is invalid |
WLM_BADFLAGS | Invalid flags value |
WLM_BADGID | The specified group ID is not valid on the system |
WLM_BADGRP | The specified group ID is not valid on the system |
WLM_BADINHER | The value specified for the class inheritance attribute is invalid |
WLM_BADHARDTOTALLIMIT | Invalid total limit (under minimum) |
WLM_BADHMAX | The hard maximum limit values must be between 1 and 100 |
WLM_BADLIMFMT | Value specified for minimum or maximum resource limit is invalid |
WLM_BADLISATT | Invalid list in attributes |
WLM_BADLIST | The process attribute list of an assignment rules is invalid |
WLM_BADLOCALSHM | Bad localshm value |
WLM_BADMIN | Minimum resource limits values must be between 0 and 100 |
WLM_BADRANGEF | Invalid format for a time range |
WLM_BADRGRP | A group name specified in the rules file is invalid on the system |
WLM_BADRSET | Bad Rset attribute for a class |
WLM_BADRUSR | A user name specified in the rules file is invalid on the system |
WLM_BADSHARES | Shares values must be between 1 and 65535 |
WLM_BADSMAX | The soft maximum limit values must be between 1 and 100 |
WLM_BADSHRFMT | Value specified for resource shares is invalid |
WLM_BADSUBLIMIT | A subclass total limit exceeds its superclass limit: The superclass limit will be used (warning) |
WLM_BADSUPER | Bad superclass for subclass assignment |
WLM_BADTIER | Tier values must be between 0 and 9 |
WLM_BADTAG | An invalid tag is specified in a rule |
WLM_BADTYP | Invalid process type in rules |
WLM_BADUID | The specified user ID is not valid on the system |
WLM_BADUSR | The specified user ID is not valid on the system |
WLM_BADVERS | Bad version number passed in the versflags field |
WLM_CANTASSIGN | Could not make assignment (Internal error) |
WLM_CANTCHECK | Unable to check the configuration |
WLM_CANTSETTAG | Could not set tag (Internal error) |
WLM_CHOWNERR | Cannot change file ownership |
WLM_CLASSMIS | No class description found |
WLM_CONFNOTFND | No configuration found for this time |
WLM_CONFNOTINSET | Configuration not found in the set |
WLM_CREATERR | A file could not be created |
WLM_DAEMONCMD | Invalid WLM daemon command |
WLM_DAEMONFAIL | WLM daemon failed to update configuration |
WLM_DUPKEY | 2 classes have the same key (warning) |
WLM_EFAULT | Bad parameter address |
WLM_EMPTYATTR | No valid process attributes found |
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_EPERM | Permission denied |
WLM_ESRCH | No such processes |
WLM_EXCLATTR | Exclusions not allowed in attributes |
WLM_EXISTS | The specified class already exists |
WLM_HASSUBS | The target superclass has subclasses |
WLM_IGNRULE | This rule is likely to be ignored (warning) |
WLM_ISCONFSET | This operation cannot apply to a configuration set |
WLM_INVRANGE | Invalid time range |
WLM_ISLOCKED | WLM configuration is locked: retry the operation later |
WLM_LOADERR | A class cannot be loaded into the kernel |
WLM_LOCKERR | Cannot lock file |
WLM_MANYRULES | Too many assignment rules |
WLM_MANYITEMS | Too many items in an assignment rule |
WLM_MAXCLASSES | The maximum number of classes has been reached |
WLM_MINSMAX | The minimum limit cannot be greater than the soft maximum limit |
WLM_MKDIRERR | A directory could not be created |
WLM_MULTATTGP | Attribute Value Grouping already defined |
WLM_MULTATTR | Multiple specifications not allowed in attributes |
WLM_NOADMINSUB | Admin attributes not applicable to subclasses |
WLM_NOCLASS | The specified class does not exist |
WLM_NOCONFIG | Missing configuration name |
WLM_NOCONFINSET | No configuration in the set |
WLM_NOCONNECT | Failure to connect to WLM daemon |
WLM_NODAEMON | Failure to start WLM daemon |
WLM_NOMEM | Not enough memory |
WLM_NOSHRRULE | Cannot specify rule for Shared class |
WLM_NOSUBS | The target superclass has no subclasses |
WLM_NOSYSMAX | Hardmax not allowed on memory for System class |
WLM_NOTASSGND | Process is not assigned |
WLM_NOTCOMPLETE | Could not assign all processes (warning) |
WLM_NOTCURRENT | Superclass update only applies to current configuration |
WLM_NOTINITED | No prior call to the wlm_initialize subroutine |
WLM_NOTRUNNING | WLM is not running |
WLM_NOWILDCRD | Wildcards not allowed in this field |
WLM_ONEDEFAULT | Only one default time range allowed in a set |
WLM_OPENERR | A file could not be opened |
WLM_QUERYERR | Cannot query WLM state |
WLM_READERR | Cannot read file |
WLM_REFRULE | A class is still referred to by rules |
WLM_REMERR | An attempt to remove a file did not succeed |
WLM_RENAMERR | An attempt to rename a file did not succeed |
WLM_RMPREDEF | Predefined classes (such as Default and System) cannot be removed |
WLM_RNOCLASS | A class specified in the rules file does not exist |
WLM_RSVDNAME | Predefined classes cannot be redefined |
WLM_RULERR | An assignment rule has an invalid format |
WLM_RULESERR | The assignment rules table cannot be loaded into the kernel |
WLM_RULTOOLNG | Rule too long |
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. |
WLM_RUNERRATT | Cannot expand attribute |
WLM_SETERR | The WLM state transition requested is illegal |
WLM_SHAREDLIM | Shared class can have shares and limits set only for memory |
WLM_SHAREDSUB | Shared superclass cannot have subclasses |
WLM_SMAXHMAX | The soft maximum limit cannot be greater than the hard maximum limit |
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_SUBINVALID | No subclass specification allowed for this operation |
WLM_SUMMINS | The sum that the minimum limits for a given resource and a given tier cannot exceed 100% |
WLM_SYMLERR | An attempt to create a symbolic link did not succeed |
WLM_TAGTOOLONG | Tag is too long |
WLM_TOOLONG | The specified class name is too long |
WLM_TOOLONGATT | Attribute list too long |
WLM_TOOMANYATT | Too many items in attributes |
WLM_TOOMANYPID | Process ID list too long |
WLM_TOOSMALL | Output buffer too small |
WLM_TOTALLIMITOUTOFRANGE | Invalid total limit (outside allowed range) |
WLM_TRGAPS | Gaps between time ranges in a configuration set |
WLM_TRINDEFAULT | Time range not allowed in default stanza |
WLM_TROVERLAP | Time ranges overlap in a configuration set |
WLM_UNLOADERR | Cannot unload class |
WLM_UNSUPP | Operation or flags value not supported |
WLM_WILDCRDATT | Wildcards not allowed in this attribute field |
WLM_WRITERR | An attempt to write to a file did not succeed |
The wlm_init_class_definition subroutine, wlm_assign subroutine, wlm_get_info subroutine.
Chapter 13. Workload Management in AIX 5L Version 5.2 System Management Concepts: Operating System and Devices