libpool(3LIB) Interface Libraries libpool(3LIB)NAMElibpool - pool configuration manipulation library
SYNOPSIS
cc [ flag... ] file... [ library... ]
#include <pool.h>
DESCRIPTION
The functions in this library define the interface for reading and
writing resource pools configuration files, as well as that for commit‐
ing 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. Processor sets and other enti‐
ties can be configured, grouped, and labelled in a persistent fashion
such that workload components can be associated with a subset of a sys‐
tem's total resources. The libpool library provides a C language API
for accessing this functionality, while pooladm(1M), poolbind(1M), and
poolcfg(1M) make this facility available through command invocations
from a shell. Each of those manual pages describes aspects of the pools
facility; this page describes the properties available to the various
entities managed within the pools facility. These entities include the
system, pools, and the pset resources for processor sets.
When the pools facility is enabled on a system, the behavior of the
following functions is modified.
System Call Error Value
───────────────────────────────────────────────────────────
pset_assign(pset !=PS_QUERY) ENOTSUP
pset_bind(pset !=PS_QUERY) ENOTSUP
pset_create() ENOTSUP
pset_destroy() ENOTSUP
pset_setattr() ENOTSUP
Each active entity within the resource pools framework can have an
arbitrary collection of named, typed properties associated with it.
Properties supported by the pools framework are listed, with descrip‐
tions, under each entity below. In general, resource properties can be
one of five types: boolean (bool), signed (int64) and unsigned (uint64)
integers, floating point (double), and string values.
All entities and resources 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 com‐
ment 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.
System
Property name Type Description
system.allocate-method string Allocation method to use when
this configuration is instanti‐
ated
system.bind-default bool If specified pool not found,
bind to pool with 'pool.default'
property set to true
system.comment string User description of system
system.name string User name for the configuration
system.version int64 libpool version required to
manipulate this configuration
system.poold.log-level string poold logging level
system.poold.log-location string poold logging location
system.poold.history-file string poold decision history location
system.poold.monitor-interval uint64 poold monitoring sample interval
system.poold.objectives string poold objectives for a system.
The system.allocate-method, system.bind-default, system.comment, sys‐
tem.name, system.poold.log-level, system.poold.log-location, sys‐
tem.poold.history-file, system.poold.monitor-interval, and sys‐
tem.poold.objectives properties are writable; the system.version prop‐
erty is not.
The system.allocate-method property accepts only two values, "impor‐
tance based" and "surplus to default". The default value for this prop‐
erty is "importance based". The property is optional and if it is not
present the library will allocate resources 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 during a commit the
library will allocate resources to pools using an algorithm that
observes minimum and maximum constraints for resources but favors those
resources with greater importance.
If "surplus to default" is defined, then during a commit the library
will allocate minimum resources to all resource sets apart from default
which will receive any surplus.
The system.bind-default property defaults to true. This property inter‐
acts with the project.pool resource control 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 reconfigura‐
tion, then this property controls the binding behavior for the project
member. If system.bind-default is true, then the project member is
bound to the default pool (identified as the pool for which
pool.default is true); otherise the project member is refused access to
the system. Care should be taken with the pools configuration if this
property is set to false, so as to avoid denying users access to the
system.
The various poold properties are used to configure the operation of
poold(1M).
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 sys‐
log(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" indi‐
cates that logged messages should be written to syslog(). If this prop‐
erty 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 deci‐
sion 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 utiliza‐
tion statistics. If this property is not specified, the default value
of 15 seconds is used.
The system.poold.objectives property specifies any system wide objec‐
tives. 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 signifi‐
cance 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 resource
allocations to resource utilization. A resource set that uses more
resources will be given more resources when this objective is active.
An administrator should use this objective when he is relatively satis‐
fied with the constraints established using the minimum and maximum
properties and would like the DRP to manipulate resources freely within
those constraints.
Pools
Property name Type Description
pool.active bool Mark this pool as active, if true.
pool.comment string User description of pool.
pool.default bool Mark this pool as the default
pool, if true; see system.bind-
default property.
pool.importance int64 Relative importance of this pool;
for possible resource dispute res‐
olution.
pool.name string User name for pool; used by set‐
project(3PROJECT) as value for
'project.pool' project attribute
in project(4) database.
pool.scheduler 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.
pool.sys_id int64 System-assigned pool ID.
pool.temporary bool Mark this pool as a temporary
resource; if true, this pool can
exist only in the dynamic configu‐
ration and cannot be committed to
a configuration file.
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 -c option for priocntl(1) for
a list of valid class names.
Processor Sets
Property name Type Description
pset.comment string User description of resource.
pset.default bool Marks default processor set.
pset.load uint64 The load for this processor set.
pset.max uint64 Maximum number of CPUs permitted
in this processor set.
pset.min uint64 Minimum number of CPUs permitted
in this processor set.
pset.name string User name for resource.
pset.size uint64 Current number of CPUs in this
processor set.
pset.sys_id int64 System-assigned processor set ID.
pset.temporary bool Mark this processor set as a tem‐
porary resource; if true, this
processor set can exist only in
the dynamic configuration and
cannot be committed to a configu‐
ration file.
pset.type string Names resource type; value for
all processor sets is pset.
pset.units string Identifies meaning of size-
related properties; value for all
processor sets is population.
pset.poold.objectives string Specifies the poold objectives
for a pset.
The pset.comment, pset.max, pset.min, pset.name, and pset.poold.objec‐
tives properties are writable; the pset.default, pset.load, pset.size,
pset.sys_id, pset.temporary, pset.type, and pset.units properties are
not.
The pset.load property represents the load on a processor set. The low‐
est 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 spe‐
cific 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:
locality This objective influences the impact that locality, as
measured by lgroup data, has upon the chosen configura‐
tion. This objective can take one of three values:
tight If set, configurations that maximize resource
locality are favored.
loose If set, configurations that minimize resource
locality are favored.
none This is the default value for this objective.
If set, configuration favorability is uninflu‐
enced by resource locality.
utilization This objective favors configurations that allocate
resources to partitions 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 speci‐
fied 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 fluctu‐
ation 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 pos‐
sible to set a < and a > operator together; the values will be vali‐
dated to ensure that they do not overlap.
Processors
Property name Type Description
─────────────────────────────────────────────────────────────────────
cpu.comment string User description of CPU.
cpu.pinned bool CPU pinned to this processor set.
cpu.status int64 Processor status, on-line, off‐
line or interrupts disabled.
cpu.sys_id 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:
off-line Set the CPU offline.
on-line Set the CPU online.
no-intr Disable interrupt processing on the CPU.
These values are defined in <sys/processor.h> as the PS_OFFLINE,
PS_ONLINE, and PS_NOINTR macros.
INTERFACES
The shared object libpool.so.1 provides the public interfaces defined
below. See Intro(3) for additional information on shared object inter‐
faces.
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_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
FILES
/usr/lib/libpool.so.1 shared object
/usr/lib/64/libpool.so.1 64-bit shared object
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬────────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼────────────────────────────────┤
│Availability │service/resource-pools (32-bit) │
├─────────────────────────────┼────────────────────────────────┤
│ │SUNWpoolx (64-bit) │
├─────────────────────────────┼────────────────────────────────┤
│CSI │Enabled │
├─────────────────────────────┼────────────────────────────────┤
│Interface Stability │Uncommitted │
├─────────────────────────────┼────────────────────────────────┤
│MT-Level │Safe │
└─────────────────────────────┴────────────────────────────────┘
SEE ALSOIntro(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), attributes(5), smf(5)NOTES
Functions in libpool can be used to manipulate static configurations
even when the pools facility is not enabled. See pooladm(1M) and
pool_set_status(3POOL) for more information about enabling the pools
facility. The pools facility must be enabled, however, to modify the
dynamic configuration.
Since the Resource Pools facility is an smf(5) service, it can also be
enabled and disabled using the standard Service Management Facility
(SMF) interfaces.
SunOS 5.11 14 Dec 2006 libpool(3LIB)
