path: root/usr/src/man/man3lib/libpool.3lib

'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LIBPOOL 3LIB "Dec 14, 2006"
.SH NAME
libpool \- pool configuration manipulation library
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
#include <\fBpool.h\fR>
.fi

.SH DESCRIPTION
.sp
.LP
The functions in this library define the interface for reading and writing
resource pools configuration files, as well as that for commiting an existing
configuration to becoming the running OS configuration (with respect to
partitioning subsystems). The <\fBpool.h\fR> header provides type and function
declarations for all library services.
.sp
.LP
The resource pools facility brings together process-bindable resources into a
common abstraction called a pool. Processor sets and other entities can be
configured, grouped, and labelled in a persistent fashion such that workload
components can be associated with a subset of a system's total resources. The
\fBlibpool\fR library provides a C language API for accessing this
functionality, while \fBpooladm\fR(1M), \fBpoolbind\fR(1M), and
\fBpoolcfg\fR(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
\fBpset\fR resources for processor sets.
.sp
.LP
When the pools facility is enabled on a system, the behavior of the following
functions is modified.
.sp

.sp
.TS
c c
l l .
System Call	Error Value
_
\fBpset_assign\fR(pset !=\fBPS_QUERY\fR)	\fBENOTSUP\fR
\fBpset_bind\fR(pset !=\fBPS_QUERY\fR)	\fBENOTSUP\fR
\fBpset_create()\fR	\fBENOTSUP\fR
\fBpset_destroy()\fR	\fBENOTSUP\fR
\fBpset_setattr()\fR	\fBENOTSUP\fR
.TE

.sp
.LP
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 descriptions, under each entity below.
In general, resource properties can be one of five types: boolean (\fBbool\fR),
signed (\fBint64\fR) and unsigned (\fBuint64\fR) integers, floating point
(\fBdouble\fR), and \fBstring\fR values.
.sp
.LP
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 comment field is not
used by the default pools commands, except when a configuration is initiated by
the \fBpoolcfg\fR utility, in which case an informative message is placed in
the \fBsystem.comment\fR property for that configuration.
.SS "System"
.sp

.sp
.TS
c c c
l l l .
Property name	Type	Description
\fBsystem.allocate-method\fR	\fBstring\fR	T{
Allocation method to use when this configuration is instantiated
T}
\fBsystem.bind-default\fR	\fBbool\fR	T{
If specified pool not found, bind to pool with 'pool.default' property set to true
T}
\fBsystem.comment\fR	\fBstring\fR	User description of system
\fBsystem.name\fR	\fBstring\fR	User name for the configuration
\fBsystem.version\fR	\fBint64\fR	T{
\fBlibpool\fR version required to manipulate this configuration
T}
\fBsystem.poold.log-level\fR	\fBstring\fR	\fBpoold\fR logging level
\fBsystem.poold.log-location\fR	\fBstring\fR	\fBpoold\fR logging location
\fBsystem.poold.history-file\fR	\fBstring\fR	\fBpoold\fR decision history location
\fBsystem.poold.monitor-interval\fR	\fBuint64\fR	\fBpoold\fR monitoring sample interval
\fBsystem.poold.objectives\fR	\fBstring\fR	\fBpoold\fR objectives for a system.
.TE

.sp
.LP
The \fBsystem.allocate-method\fR, \fBsystem.bind-default\fR,
\fBsystem.comment\fR, \fBsystem.name\fR, \fBsystem.poold.log-level\fR,
\fBsystem.poold.log-location\fR, \fBsystem.poold.history-file\fR,
\fBsystem.poold.monitor-interval\fR, and \fBsystem.poold.objectives\fR
properties are writable; the \fBsystem.version\fR property is not.
.sp
.LP
The \fBsystem.allocate-method\fR 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 resources as though it were present and had the default
value. These strings are defined in <\fBpool.h\fR> as \fBPOA_IMPORTANCE\fR and
\fBPOA_SURPLUS_TO_DEFAULT\fR.
.sp
.LP
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.
.sp
.LP
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.
.sp
.LP
The \fBsystem.bind-default\fR property defaults to true. This property
interacts with the \fBproject.pool\fR resource control to specify the binding
behavior for processes associated with a project. If \fBproject.pool\fR is not
specified, then this property has no effect. If \fBproject.pool\fR 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. If
\fBsystem.bind-default\fR is true, then the project member is bound to the
default pool (identified as the pool for which \fBpool.default\fR 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.
.sp
.LP
The various \fBpoold\fR properties are used to configure the operation of
\fBpoold\fR(1M).
.sp
.LP
The \fBsystem.poold.log-level\fR property is used to specify the level of
detail provided in log messages. Valid values are: \fBALERT\fR, \fBCRIT\fR,
\fBERR\fR, \fBWARNING\fR, \fBNOTICE\fR, \fBINFO\fR, and \fBDEBUG\fR.
.sp
.LP
\fBALERT\fR provides the least level of detail, \fBDEBUG\fR the greatest. See
\fBsyslog\fR(3C) for more information about the meaning of these debug levels.
If this property is not specified, the default value \fBNOTICE\fR is used.
.sp
.LP
The \fBsystem.poold.log-location\fR property is used to specify the location of
the logfiles generated by \fBpoold\fR. The special value of "syslog" indicates
that logged messages should be written to \fBsyslog()\fR. If this property is
not specified, the default location \fB/var/log/pool\fR is used.
.sp
.LP
The \fBsystem.poold.history-file\fR specifies the location of the decision
history file which is used by \fBpoold\fR to improve the quality of its
decision making over time. If this property is not specified, the default
location \fB/var/adm/pool\fR is used.
.sp
.LP
The \fBsystem.poold.monitor-interval\fR property specifies the monitoring
interval (in milliseconds) to be used by \fBpoold\fR when sampling utilization
statistics. If this property is not specified, the default value of 15 seconds
is used.
.sp
.LP
The \fBsystem.poold.objectives\fR property specifies any system wide
objectives. An objectives property has the following syntax:
.sp
.in +2
.nf
objectives = objective [; objective]*
objective = [n:] keyword [op] [value]
.fi
.in -2

.sp
.LP
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.
.sp
.LP
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 satisfied with the constraints established
using the minimum and maximum properties and would like the DRP to manipulate
resources freely within those constraints.
.SS "Pools"
.sp

.sp
.TS
c c c
l l l .
Property name	Type	Description
\fBpool.active\fR	\fBbool\fR	Mark this pool as active, if true.
\fBpool.comment\fR	\fBstring\fR	User description of pool.
\fBpool.default\fR	\fBbool\fR	T{
Mark this pool as the default pool, if true; see system.bind-default property.
T}
\fBpool.importance\fR	\fBint64\fR	T{
Relative importance of this pool; for possible resource dispute resolution.
T}
\fBpool.name\fR	\fBstring\fR	T{
User name for pool; used by \fBsetproject\fR(3PROJECT) as value for 'project.pool' project attribute in \fBproject\fR(4) database.
T}
\fBpool.scheduler\fR	\fBstring\fR	T{
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.
T}
\fBpool.sys_id\fR	\fBint64\fR	System-assigned pool ID.
\fBpool.temporary\fR	\fBbool\fR	T{
Mark this pool as a temporary resource; if true, this pool can exist only in the dynamic configuration and cannot be committed to a configuration file.
T}
.TE

.sp
.LP
The \fBpool.default\fR, \fBpool.sys_id\fR, and \fBpool.temporary\fR properties
are not writable; all other listed properties are writable.
.sp
.LP
If pool.scheduler is specified, it must be set to the name of a valid
scheduling class for the system. See the \fB-c\fR option for \fBpriocntl\fR(1)
for a list of valid class names.
.SS "Processor Sets"
.sp

.sp
.TS
c c c
l l l .
Property name	Type	Description
\fBpset.comment\fR	\fBstring\fR	User description of resource.
\fBpset.default\fR	\fBbool\fR	Marks default processor set.
\fBpset.load\fR	\fBuint64\fR	The load for this processor set.
\fBpset.max\fR	\fBuint64\fR	T{
Maximum number of CPUs permitted in this processor set.
T}
\fBpset.min\fR	\fBuint64\fR	T{
Minimum number of CPUs permitted in this processor set.
T}
\fBpset.name\fR	\fBstring\fR	User name for resource.
\fBpset.size\fR	\fBuint64\fR	T{
Current number of CPUs in this processor set.
T}
\fBpset.sys_id\fR	\fBint64\fR	System-assigned processor set ID.
\fBpset.temporary\fR	\fBbool\fR	T{
Mark this processor set as a temporary resource; if true, this processor set can exist only in the dynamic configuration and cannot be committed to a configuration file.
T}
\fBpset.type\fR	\fBstring\fR	T{
Names resource type; value for all processor sets is \fBpset\fR.
T}
\fBpset.units\fR	\fBstring\fR	T{
Identifies meaning of size-related properties; value for all processor sets is \fBpopulation\fR.
T}
\fBpset.poold.objectives\fR	\fBstring\fR	T{
Specifies the poold objectives for a pset.
T}
.TE

.sp
.LP
The \fBpset.comment\fR, \fBpset.max\fR, \fBpset.min\fR, \fBpset.name\fR, and
\fBpset.poold.objectives\fR properties are writable; the \fBpset.default\fR,
\fBpset.load\fR, \fBpset.size\fR, \fBpset.sys_id\fR, \fBpset.temporary\fR,
\fBpset.type\fR, and \fBpset.units\fR properties are not.
.sp
.LP
The \fBpset.load\fR property represents the load on a processor set. The lowest
value for this property is 0. The value of \fBpset.load\fR increases in a
linear fashion with the load on the set, as measured by the number of jobs in
the system run queue.
.sp
.LP
The \fBpset.poold.objectives\fR property specifies an objective which is
specific to a particular \fBpset\fR. See the \fBsystem.poold.objectives\fR
entry for the specification of this property's syntax.
.sp
.LP
There are two types of objectives that can be set on a \fBpset\fR:
.sp
.ne 2
.na
\fB\fBlocality\fR\fR
.ad
.RS 15n
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:
.sp
.ne 2
.na
\fB\fBtight\fR\fR
.ad
.RS 9n
If set, configurations that maximize resource locality are favored.
.RE

.sp
.ne 2
.na
\fB\fBloose\fR\fR
.ad
.RS 9n
If set, configurations that minimize resource locality are favored.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 9n
This is the default value for this objective. If set, configuration
favorability is uninfluenced by resource locality.
.RE

.RE

.sp
.ne 2
.na
\fB\fButilization\fR\fR
.ad
.RS 15n
This objective favors configurations that allocate resources to partitions that
are failing to preserve the specified utilization objective.
.RE

.sp
.LP
These objectives are specified in terms of an operator and a value. The
operators are
.sp
.ne 2
.na
\fB\fB<\fR\fR
.ad
.RS 5n
The ``less than'' operator is used to indicate that the specified value should
be treated as a maximum target value.
.RE

.sp
.ne 2
.na
\fB\fB>\fR\fR
.ad
.RS 5n
The ``greater than'' operator is used to indicate that the specified value
should be treated as a minimum target value.
.RE

.sp
.ne 2
.na
\fB\fB~\fR\fR
.ad
.RS 5n
The ``about'' operator is used to indicate that the specified value should be
treated as a target value about which some fluctuation is acceptable.
.RE

.sp
.LP
Only one objective of each type of operator can be set. For example, if the
\fB~\fR operator is set, the \fB<\fR and \fB>\fR operators cannot be set. It is
possible to set a \fB<\fR and a \fB>\fR operator together; the values will be
validated to ensure that they do not overlap.
.SS "Processors"
.sp

.sp
.TS
c c c
l l l .
Property name	Type	Description
_
\fBcpu.comment\fR	\fBstring\fR	User description of CPU.
\fBcpu.pinned\fR	\fBbool\fR	CPU pinned to this processor set.
\fBcpu.status\fR	\fBint64\fR	T{
Processor status, on-line, offline or interrupts disabled.
T}
\fBcpu.sys_id\fR	\fBint64\fR	System-assigned processor ID.
.TE

.sp
.LP
The \fBcpu.comment\fR, \fBcpu.pinned\fR, and \fBcpu.status\fR properties are
writeable.
.sp
.LP
The \fBcpu.status\fR property can be set only to the following values:
.sp
.ne 2
.na
\fB\fBoff-line\fR\fR
.ad
.RS 12n
Set the CPU offline.
.RE

.sp
.ne 2
.na
\fB\fBon-line\fR\fR
.ad
.RS 12n
Set the CPU online.
.RE

.sp
.ne 2
.na
\fB\fBno-intr\fR\fR
.ad
.RS 12n
Disable interrupt processing on the CPU.
.RE

.sp
.LP
These values are defined in <\fBsys/processor.h\fR> as the \fBPS_OFFLINE\fR,
\fBPS_ONLINE\fR, and \fBPS_NOINTR\fR macros.
.SH INTERFACES
.sp
.LP
The shared object \fBlibpool.so.1\fR provides the public interfaces defined
below. See \fBIntro\fR(3) for additional information on shared object
interfaces.
.sp

.sp
.TS
l l
l l .
\fBpool_associate\fR	\fBpool_component_info\fR
\fBpool_component_to_elem\fR	\fBpool_conf_alloc\fR
\fBpool_conf_close\fR	\fBpool_conf_commit\fR
\fBpool_conf_export\fR	\fBpool_conf_free\fR
\fBpool_conf_info\fR	\fBpool_conf_location\fR
\fBpool_conf_open\fR	\fBpool_conf_remove\fR
\fBpool_conf_rollback\fR	\fBpool_conf_status\fR
\fBpool_conf_to_elem\fR	\fBpool_conf_update\fR
\fBpool_conf_validate\fR	\fBpool_create\fR
\fBpool_destroy\fR	\fBpool_dissociate\fR
\fBpool_dynamic_location\fR	\fBpool_error\fR
\fBpool_get_binding\fR	\fBpool_get_owning_resource\fR
\fBpool_get_pool\fR	\fBpool_get_property\fR
\fBpool_get_resource\fR	\fBpool_get_resource_binding\fR
\fBpool_get_status\fR	\fBpool_info\fR
\fBpool_put_property\fR	\fBpool_query_components\fR
\fBpool_query_pool_resources\fR	\fBpool_query_pools\fR
\fBpool_query_resource_components\fR	\fBpool_query_resources\fR
\fBpool_resource_create\fR	\fBpool_resource_destroy\fR
\fBpool_resource_info\fR	\fBpool_resource_to_elem\fR
\fBpool_resource_transfer\fR	\fBpool_resource_type_list\fR
\fBpool_resource_xtransfer\fR	\fBpool_rm_property\fR
\fBpool_set_binding\fR	\fBpool_set_status\fR
\fBpool_static_location\fR	\fBpool_strerror\fR
\fBpool_to_elem\fR	\fBpool_value_alloc\fR
\fBpool_value_free\fR	\fBpool_value_get_bool\fR
\fBpool_value_get_double\fR	\fBpool_value_get_int64\fR
\fBpool_value_get_name\fR	\fBpool_value_get_string\fR
\fBpool_value_get_type\fR	\fBpool_value_get_uint64\fR
\fBpool_value_set_bool\fR	\fBpool_value_set_double\fR
\fBpool_value_set_int64\fR	\fBpool_value_set_name\fR
\fBpool_value_set_string\fR	\fBpool_value_set_uint64\fR
\fBpool_version\fR	\fBpool_walk_components\fR
\fBpool_walk_pools\fR	\fBpool_walk_properties\fR
\fBpool_walk_resources\fR	
.TE

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/libpool.so.1\fR\fR
.ad
.RS 28n
shared object
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/64/libpool.so.1\fR\fR
.ad
.RS 28n
64-bit shared object
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Unstable
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBIntro\fR(3), \fBpool_component_info\fR(3POOL), \fBpool_conf_open\fR(3POOL),
\fBpool_conf_to_elem\fR(3POOL), \fBpool_create\fR(3POOL),
\fBpool_error\fR(3POOL), \fBpool_get_binding\fR(3POOL),
\fBpool_get_property\fR(3POOL), \fBpool_get_resource\fR(3POOL),
\fBpool_resource_create\fR(3POOL), \fBpool_value_alloc\fR(3POOL),
\fBpool_walk_pools\fR(3POOL), \fBattributes\fR(5), \fBsmf\fR(5)
.SH NOTES
.sp
.LP
Functions in \fBlibpool\fR can be used to manipulate static configurations even
when the pools facility is not enabled. See \fBpooladm\fR(1M) and
\fBpool_set_status\fR(3POOL) for more information about enabling the pools
facility. The pools facility must be enabled, however, to modify the dynamic
configuration.
.sp
.LP
Since the Resource Pools facility is an \fBsmf\fR(5) service, it can also be
enabled and disabled using the standard Service Management Facility (SMF)
interfaces.