[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Files Reference


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, 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

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:

min
Specifies the minimum value, which is between 0 (the default) and 100

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.

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.

hardmax
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.

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.

 

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.

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:

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

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:

consum
Specifies the resource consumption of the class. This value is expressed as a percentage of the total resource available.

total
Specifies the 64-bit number that represents the total amount of the resource consumed by the class since its creation (or since WLM was started). The value can be the number of milliseconds for CPU, the number of pages multiplied by seconds for memory, and the total number of 512-byte blocks for disk I/O.

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.

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_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:
  • Resource utilization, which is expressed as a percentage of the total available throughput of the device (consum)
  • Total number of 512-byte blocks read/written from and to the device by processes in the class since it was created, or since WLM started, whichever happened most recently
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:

Index
Description

WBS_OUT_RTHRPUT
Specifies the number of blocks actually read from the device (I/O completed)

WBS_OUT_WTHRPUT
Specifies the number of blocks actually written to the device (I/O completed)

WBS_IN_RTHRPUT
Specifies the requested number of blocks to be read from the device

WBS_IN_WTHRPUT
Specifies the requested number of blocks to write to the device

WBS_REQUESTS
Specifies the number of read/write requests

WBS_QUEUED
Specifies the number of requests queued

WBS_STARVED
Specifies the number of requests starved (not serviced during the time interval)
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.

Error Codes

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.

Implementation Specifics

This file is part of Base Operating System (BOS) Runtime.

Related Information

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


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]