libpool - pool configuration manipulation library
cc [ flag... ] file... –lpool [ library... ] #include <pool.h>
The functions in this library define the interface for reading and writing resource pool configuration files, as well as that for applying an existing configuration to becoming the running OS configuration (with respect to partitioning subsystems). The <pool.h> header provides type and function declarations for all library services.
The resource pools facility brings together process-bindable resources into a common abstraction called a pool. The only currently supported resource type is pset, which can be allocated or assigned cpu components. Every pool is associated with a single pset. Pools can be configured in a persistent fashion such that workloads can be associated with a subset of a system's total resources. The libpool library provides a C language API for accessing this functionality, while pooladm(8), poolbind(8), and poolcfg(8) make this facility available through command invocations from a shell. Each of those manual pages describes aspects of the resource pools facility; this page describes the properties available to the various entities managed within the resource pools facility. These entities include the system, pool, and the pset resources and the cpu components.
The resource pools facility cannot be used to modify psets created by psrset(8). This includes assigning or transferring CPUs that are already assigned to psrset(8) psets. See psrset(8) to manipulate such psets.
Each active entity within the resource pools framework can have an arbitrary collection of named, typed properties associated with it. Properties supported by the resource pools framework are listed, with descriptions, under each entity below. In general, properties can be one of five types: boolean (bool), signed (int64) and unsigned (uint64) integers, floating point (double), and string values.
All entities support a string property for commenting purposes; this property is available for use by management applications to record descriptions and other administrator oriented data. The comment field is not used by the default pools commands, except when a configuration is initiated by the poolcfg utility, in which case an informative message is placed in the system.comment property for that configuration.
Type: string
Allocation method to use when this configuration is instantiated
Type: bool
If project.pool of a project is not found, bind processes in that project to the pool the zone is currently bound to.
Type: bool
If the specified pool of a zone is not found, bind the zone to the default pool. This property does not affect the global zone.
Type: string
User description of system
Type: int64
libpool version required to manipulate this configuration
Type: string
poold logging level
Type: string
poold logging location
Type: string
poold decision history location
Type: uint64
poold monitoring sample interval
Type: string
poold objectives for a system.
The system.allocate-method, system.project-fallback-to-default, system.zone-fallback-to-default, system.comment, system.poold.log-level, system.poold.log-location, system.poold.history-file, system.poold.monitor-interval, and system.poold.objectives properties are writable; the system.version property is not.
Property system.bind-default is retained for backward compatibility, and is aliased to system.project-fallback-to-default. This might be removed in a future release of Oracle Solaris.
The system.allocate-method property accepts only two values, importance based and surplus to default. The default value for this property is importance based. The property is optional and if it is not present the library will allocate CPUs as though it were present and had the default value. These strings are defined in <pool.h> as POA_IMPORTANCE and POA_SURPLUS_TO_DEFAULT.
If importance based allocation is defined, then when a configuration file is applied, the library will allocate CPUs to psets using an algorithm that observes minimum and maximum constraints for psets but favors those psets associated with pools of greater importance.
If surplus to default is defined, then when a configuration file is applied, library will allocate minimum CPUs to all psets apart from pset_default which will receive any surplus.
The system.project-fallback-to-default property defaults to true. This property interacts with the project.pool property to specify the binding behavior for processes associated with a project. If project.pool is not specified, then this property has no effect. If project.pool is specified and the specified pool exists, this property has no effect. If the specified pool does not exist, perhaps because of a reconfiguration, then this property controls the binding behavior for the project member such as, if system.project-fallback-to-default is true, then the project member is bound to a pool that the zone (be it a global zone or a non-global zone) is presently bound to; otherwise the project member is refused access to the system. Care should be taken with the pool configuration if this property is set to false, so as to avoid denying users access to the system.
The system.zone-fallback-to-default property defaults to false. If a pool is not specified for a zone via the pool property in the zone configuration then this property has no effect. If a pool is specified for a zone and the zone binds to it, this property has no effect. If the pool specified in the zone config does not exist then system.zone-fallback-to-default controls the binding behavior for the zone. If set to true, the zone is bound to the default pool; otherwise the zone fails to boot and an error is printed.
The various poold properties are used to configure the operation of poold(8).
The system.poold.log-level property is used to specify the level of detail provided in log messages. Valid values are: ALERT, CRIT, ERR, WARNING, NOTICE, INFO, and DEBUG.
ALERT provides the least level of detail, DEBUG the greatest. See syslog(3C) for more information about the meaning of these debug levels. If this property is not specified, the default value NOTICE is used.
The system.poold.log-location property is used to specify the location of the logfiles generated by poold. The special value of “syslog” indicates that logged messages should be written to syslog(). If this property is not specified, the default location /var/log/pool is used.
The system.poold.history-file specifies the location of the decision history file which is used by poold to improve the quality of its decision making over time. If this property is not specified, the default location /var/adm/pool is used.
The system.poold.monitor-interval property specifies the monitoring interval (in milliseconds) to be used by poold when sampling utilization statistics. If this property is not specified, the default value of 15 seconds is used.
The system.poold.objectives property specifies any system wide objectives. An objectives property has the following syntax:
objectives = objective [; objective]* objective = [n:] keyword [op] [value]
All objectives are prefixed with an optional importance. The importance acts as a multiplier for the objective and thus increases the significance of its contribution to the objective function evaluation. If no importance is specified, the default value is 1.
The wt-load objective is the only objective to which a system element can be set. This objective favors configurations that match cpu allocations to resource utilization. A pset with busier CPUs than other psets will be given more CPUs when this objective is active. An administrator should use this objective when they are relatively satisfied with the constraints established using the minimum and maximum properties and would like the DRP to manipulate CPUs freely within those constraints.
Type: bool
Mark this pool as active, if true.
Type: string
User description of pool.
Type : bool
This pool as the default pool, if true. This property is read-only; see system.bind-default property.
Type: int64
Relative importance of this pool; pools with higher importance will be allocated more CPUs within their pset.min and pset.max constraints.
Type: string
User name for pool; used by setproject(3PROJECT) as value for 'project.pool' project attribute in project(5) database. This property is read-only for the pool with name pool_default.
Type: string
Scheduler class to which consumers of this pool will be bound. This property is optional and if not specified, the scheduler bindings for consumers of this pool are not affected.
Type: int64
System-assigned pool ID.
Type: bool
Marks this pool as a temporary; if true, this pool can exist only in the dynamic configuration and never exists in a configuration file. Temporary pools are created by the zonecfg(8) dedicated-cpu resource and by pset_create(2) or psrset(8). This property is read-only.
Type: bool
If true, this pool was created by pset_create(2) or psrset(8). All properties of such a pool are read-only.
The pool.default, pool.sys_id, and pool.temporary properties are not writable; all other listed properties are writable.
If pool.scheduler is specified, it must be set to the name of a valid scheduling class for the system. See the –l option for priocntl(1) for a list of valid class names.
Type: string
User description of pset.
Type: bool
Marks default pset. This property is read-only.
Type: uint64
The load for this pset.
Type: uint64
Maximum number of CPUs permitted in this pset.
Type: uint64
Minimum number of CPUs permitted in this pset.
Type: string
User name for pset. This property is read only for the pset with name pset_default.
Type: string
One of minmax or strict. The default is minmax.
Type: string
A comma-separated list of CPU, core, or socket IDs.
Type: uint64
One of cpu, core, or socket.
Type: uint64
Current number of CPUs in this pset.
Type: int64
System-assigned pset ID.
Type: bool
Marks this pset as a temporary. If true, this pset can exist only in the dynamic configuration and never exists in a configuration file. Temporary psets are created by the zonecfg(8) dedicated-cpu resource and by pset_create(2) or psrset(8). This property is read-only.
Type: bool
If true, this pset was created by pset_create(2) or this command. All properties of such a pset are read-only.
Type: string
Set to pset. This property is read-only.
Type: string
Identifies meaning of size-related properties; value for all psets is population.
Type: string
Specifies the poold objectives for a pset.
The pset.default, pset.load, pset.size, pset.sys_id, pset.temporary, and pset.units properties are read only.
The following properties are set by the poolcfg(8) to allocate and assign commands:
Set to cpu-type of assign command.
Defaults to minmax for setting pset.min and pset.max directly. Set to assigned by the assign command.
Set to a list of cpu, core, or socket ids by the assign command.
The pset.load property represents the load on a pset. The lowest value for this property is 0. The value of pset.load increases in a linear fashion with the load on the set, as measured by the number of jobs in the system run queue.
The pset.poold.objectives property specifies an objective which is specific to a particular pset. See the system.poold.objectives entry for the specification of this property's syntax.
There are two types of objectives that can be set on a pset:
This objective influences the impact that locality, as measured by lgroup data, has upon the chosen configuration. This objective can take one of three values:
If set, configurations that maximize CPU locality are favored.
If set, configurations that minimize CPU locality are favored.
This is the default value for this objective. If set, configuration favorability is uninfluenced by CPU locality.
This objective favors configurations that allocate CPUs to psets that are failing to preserve the specified utilization objective.
These objectives are specified in terms of an operator and a value. The operators are
The “less than” operator is used to indicate that the specified value should be treated as a maximum target value.
The “greater than” operator is used to indicate that the specified value should be treated as a minimum target value.
The “about” operator is used to indicate that the specified value should be treated as a target value about which some fluctuation is acceptable.
Only one objective of each type of operator can be set. For example, if the ~ operator is set, the < and > operators cannot be set. It is possible to set a < and a > operator together; the values will be validated to ensure that they do not overlap.
Type: string
User description of CPU.
Type: bool
CPU pinned to this pset.
Type: int64
Processor status. One of on-line, off-line, no-intr (interrupts disabled), faulted, or spare.
Type: int64
System-assigned processor ID.
The cpu.comment, cpu.pinned, and cpu.status properties are writeable.
The cpu.status property can be set only to the following values:
Set the CPU offline.
Set the CPU online.
Disable interrupt processing on the CPU.
These values are defined in <sys/processor.h> as the PS_OFFLINE, PS_ONLINE, and PS_NOINTR macros.
The shared object libpool.so.1 provides the public interfaces defined below. See intro(3) for additional information on shared object interfaces.
pool_associate pool_component_info pool_component_to_elem pool_conf_alloc pool_conf_close pool_conf_commit pool_conf_export pool_conf_free pool_conf_info pool_conf_location pool_conf_open pool_conf_remove pool_conf_rollback pool_conf_status pool_conf_to_elem pool_conf_update pool_conf_validate pool_create pool_destroy pool_dissociate pool_dynamic_location pool_error pool_get_binding pool_get_owning_resource pool_get_pool pool_get_property pool_get_resource pool_get_resource_binding pool_get_status pool_info pool_is_readonly_property pool_put_property pool_query_components pool_query_pool_resources pool_query_pools pool_query_resource_components pool_query_resources pool_resource_create pool_resource_destroy pool_resource_info pool_resource_to_elem pool_resource_transfer pool_resource_type_list pool_resource_xtransfer pool_rm_property pool_set_binding pool_set_status pool_static_location pool_strerror pool_to_elem pool_value_alloc pool_value_free pool_value_get_bool pool_value_get_double pool_value_get_int64 pool_value_get_name pool_value_get_string pool_value_get_type pool_value_get_uint64 pool_value_set_bool pool_value_set_double pool_value_set_int64 pool_value_set_name pool_value_set_string pool_value_set_uint64 pool_version pool_walk_components pool_walk_pools pool_walk_properties pool_walk_resources
shared object
64-bit shared object
See attributes(7) for descriptions of the following attributes:
|
attributes(7), intro(3), pool_component_info(3POOL), pool_conf_open(3POOL), pool_conf_to_elem(3POOL), pool_create(3POOL), pool_error(3POOL), pool_get_binding(3POOL), pool_get_property(3POOL), pool_get_resource(3POOL), pool_resource_create(3POOL), pool_value_alloc(3POOL), pool_walk_pools(3POOL), resource-management(7), smf(7)
Enabling the Resource Pools service will apply the default pool configuration file /etc/pooladm.conf, and it will continue to apply it on each system boot until the service is disabled.
Since the Resource Pools service is a standard smf(7) service, it can also be enabled and disabled using the standard Service Management Facility (SMF) interfaces. The pools service is svc:/system/pools:default.
In prior versions of Solaris, the Resource Pools service needed to be enabled in order for libpool, poolcfg(8), and pooladm(8) to function correctly. This is no longer the case. Enabling the Resource Pools service now only functions to apply the pool configuration file. The resource pools commands and libraries may now be used even if the pools service is disabled.
Resource pools now also support being used at the same time as psrset(8) psets.