This API is comprised of a set of routines in the /usr/lib/libwlm.a library, which enable applications to perform all the tasks that a WLM administrator can perform using the WLM commands, including:
In addition, the wlm_set_tag routine allows an application to set up an application tag and specify whether this tag should be inherited by child processes at fork or exec. The library provides support for multi-threaded 32-bit or 64-bit applications.
The application tag is a string of characters and is used as one of the classification criteria for the automatic classification of processes (using the rules file). This tag basically provides an application-defined classification criteria in addition to the system-defined criteria such as user, group, application and type.
When an application process sets its tag, it is immediately reclassified using the superclass and subclass rules in effect for the currently active WLM configuration. WLM then reviews the assignment rules looking for a match, using all the process attributes, including the new tag.
To be effective, this tag must appear in one or more of the assignment rules. The format and the use of the various tags by each application must be clearly specified in the application's administration documentation and well-known to the WLM administrators so that they can use the various values of the tags in their assignment rules to distinguish between different instances of the same application.
Because different users might have different requirements regarding what set of characteristics of the application processes they want to use to classify those processes, it is recommended that the application provide a set of configuration or run time attributes that can be used to build the tag. The application administrator can specify the format of this tag to the application. The attributes that can be used for the tag and the syntax to specify the format of the WLM tag are application-dependent and are the responsibility of the application provider.
For example, an instance of a database server is able to determine which database it is working on (db_name) and through which TCP port a given user is connected (port_num). Administrators might have any of the following priorities:
One way to accommodate these different needs is to specify the content and format of the tag. In this example, assume that the tag can be passed to the application in a configuration file or run time parameter such as WLM_TAG=$db_name or WLM_TAG=$db_name_$port_num.
When setting its tag, an application can specify whether this tag will be inherited by its children so that all the processes spawned by a specific instance of an application can be classified in the same class. Setting the tag inheritance is how the application tag is most commonly used.
The following is an example of how application tags could be used. In this example, the tag of the database is the same as the database name. Then two instances of the server working on two different databases would set up two different tags, for instance db1 and db2.
A system administrator could create two different classes dbserv1 and dbserv2 and classify the two database servers (and all their children if tag inheritance is used) in these classes using the tags. It would then be possible to give each class different resource entitlement according to specific business goals.
The corresponding assignment rules could look similar to the following:
* class resvd user group application type tag * dbserv1 - - dbadm /usr/sbin/dbserv - db1 dbserv2 - - dbadm /usr/sbin/dbserv - db2
The WLM API provides applications with the ability to:
The changes will be applied only to the property files of the specified WLM configuration. Optionally, by specifying an empty string as the configuration name, it is possible to apply the change only to the in-core classes, resulting in an immediate update of the active configuration state.
The API calls require from the caller the same level of privilege that would be required for the command line or for the SMIT or Web-based System Manager interfaces, as follows:
In cases where WLM administration is accomplished, both through the command line and administration tools by WLM administrators, and by application(s) through the API, some caution must be applied. Both interfaces share the same name space for the superclass and subclass names, and the total number of superclasses and subclasses.
In addition, when the API directly modifies the in-core WLM data (create new classes, for example), WLM administrators are not aware of this until classes that they did not create appear on the output of commands such as the wlmstat command. To avoid conflicts that would confuse the applications using this API when the system administrator updates WLM, the classes created through the API that are not defined in the WLM property files are not automatically removed from the in-core data. They remain in effect until explicitly removed through the wlm_delete_class routine or through an invocation of the rmclass command (invoked directly or through SMIT or Web-based System Manager by the system administrator).
The WLM API also provides applications with the ability to:
The API requires the same levels of privilege as the corresponding wlmcntrl and wlmassign commands:
The WLM API routines and wlm_get_bio_stats provide application access to the WLM statistics displayed by the wlmstat commands.
The wlm_check routine allows the user to verify the class definitions and the assignment rules for a given WLM configuration. The API routine wlm_classify (see Process to Class Assignment in WLM) allows an application to determine to which class a process with a specified set of attributes would be classified.
To provide binary compatibility if there are future changes to the data structures, each API call is passed a version number as a parameter, which will allow the library to determine with which version of the data structures the application has been built.