Movatterモバイル変換

libpool

- pool configuration manipulation library

Synopsis

cc [flag... ]file... [library... ] #include <pool.h>

Description

The functions in this library define the interface for reading and writingresource pools configuration files, as well as that for commiting an existingconfiguration 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 abstractioncalled a pool. Processor sets and other entities can be configured, grouped,and labelled in a persistent fashion such that workload components can beassociated with a subset of a system's total resources. Thelibpool library providesa C language API for accessing this functionality, whilepooladm(1M),poolbind(1M), andpoolcfg(1M) make this facility available through command invocations from a shell. Each ofthose manual pages describes aspects of the pools facility; this page describesthe properties available to the various entities managed within the pools facility.These entities include the system, pools, and thepset resources for processor sets.

When the pools facility is enabled on a system, the behavior ofthe 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 arbitrarycollection of named, typed properties associated with it. Properties supported by thepools framework are listed, with descriptions, under each entity below. In general,resource properties can be one of five types: boolean (bool), signed (int64) andunsigned (uint64) integers, floating point (double), andstring values.

All entities and resources support a string property for commenting purposes; thisproperty is available for use by management applications to record descriptions andother administrator oriented data. The comment field is not used by thedefault pools commands, except when a configuration is initiated by thepoolcfg utility,in which case an informative message is placed in thesystem.comment propertyfor that configuration.

System

Property name	Type	Description
`system.allocate-method`	`string`	Allocation method to use when this configuration is instantiated
`system.bind-default`	`bool`	Ifspecified pool not found, bind to pool with 'pool.default' property set totrue
`system.comment`	`string`	User description of system
`system.name`	`string`	User name for the configuration
`system.version`	`int64`	`libpool` version required to manipulatethis 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.

Thesystem.allocate-method,system.bind-default,system.comment,system.name,system.poold.log-level,system.poold.log-location,system.poold.history-file,system.poold.monitor-interval, andsystem.poold.objectives propertiesare writable; thesystem.version property is not.

Thesystem.allocate-method property accepts only two values, “importance based” and “surplus todefault”. The default value for this property is “importance based”. The propertyis optional and if it is not present the library will allocate resourcesas though it were present and had the default value. These stringsare defined in <pool.h> asPOA_IMPORTANCE andPOA_SURPLUS_TO_DEFAULT.

If “importance based” allocation is defined, then during a commit the librarywill allocate resources to pools using an algorithm that observes minimum andmaximum constraints for resources but favors those resources with greater importance.

If “surplus to default” is defined, then during a commit the librarywill allocate minimum resources to all resource sets apart from default whichwill receive any surplus.

Thesystem.bind-default property defaults to true. This property interacts with theproject.poolresource control to specify the binding behavior for processes associated with aproject. Ifproject.pool is not specified, then this property has no effect. Ifproject.pool is specified and the specified pool exists, this property has noeffect. If the specified pool does not exist, perhaps because of areconfiguration, then this property controls the binding behavior for the project member.Ifsystem.bind-default is true, then the project member is bound to thedefault pool (identified as the pool for whichpool.default is true); otherisethe project member is refused access to the system. Care should betaken with the pools configuration if this property is set to false, soas to avoid denying users access to the system.

The variouspoold properties are used to configure the operation ofpoold(1M).

Thesystem.poold.log-level property is used to specify the level of detail providedin log messages. Valid values are:ALERT,CRIT,ERR,WARNING,NOTICE,INFO, andDEBUG.

ALERT provides the least level of detail,DEBUG the greatest. Seesyslog(3C)for more information about the meaning of these debug levels. If this propertyis not specified, the default valueNOTICE is used.

Thesystem.poold.log-location property is used to specify the location of the logfilesgenerated bypoold. The special value of “syslog” indicates that logged messagesshould be written tosyslog(). If this property is not specified, the defaultlocation/var/log/pool is used.

Thesystem.poold.history-file specifies the location of the decision history file which isused bypoold to improve the quality of its decision making overtime. If this property is not specified, the default location/var/adm/pool is used.

Thesystem.poold.monitor-interval property specifies the monitoring interval (in milliseconds) to be usedbypoold when sampling utilization statistics. If this property is not specified,the default value of 15 seconds is used.

Thesystem.poold.objectives property specifies any system wide objectives. An objectives property hasthe following syntax:

objectives = objective [; objective]*objective = [n:] keyword [op] [value]

All objectives are prefixed with an optional importance. The importance acts asa multiplier for the objective and thus increases the significance of itscontribution to the objective function evaluation. If no importance is specified, thedefault value is 1.

The “wt-load” objective is the only objective to which a system elementcan be set. This objective favors configurations that match resource allocations toresource utilization. A resource set that uses more resources will be givenmore resources when this objective is active. An administrator should use this objectivewhen he is relatively satisfied with the constraints established using the minimumand maximum properties and would like the DRP to manipulate resources freelywithin those constraints.

Pools

Property name	Type	Description
`pool.active`	`bool`	Mark this pool as active, if true.
`pool.comment`	`string`	User description ofpool.
`pool.default`	`bool`	Mark this pool as the default pool, if true; see system.bind-default property.
`pool.importance`	`int64`	Relativeimportance of this pool; for possible resource dispute resolution.
`pool.name`	`string`	User name for pool;used by`setproject`(3PROJECT) as value for 'project.pool' project attribute in`project`(4) database.
`pool.scheduler`	`string`	Schedulerclass to which consumers of this pool will be bound. This propertyis optional and if not specified, the scheduler bindings for consumers ofthis pool are not affected.
`pool.sys_id`	`int64`	System-assigned pool ID.
`pool.temporary`	`bool`	Mark this pool as a temporaryresource; if true, this pool can exist only in the dynamic configurationand cannot be committed to a configuration file.

Thepool.default,pool.sys_id, andpool.temporary properties are not writable; all other listedproperties are writable.

If pool.scheduler is specified, it must be set to the name ofa valid scheduling class for the system. See the-c option forpriocntl(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 defaultprocessor set.
`pset.load`	`uint64`	The load for this processor set.
`pset.max`	`uint64`	Maximum number of CPUs permitted inthis processor set.
`pset.min`	`uint64`	Minimum number of CPUs permitted in this processor set.
`pset.name`	`string`	User namefor resource.
`pset.size`	`uint64`	Current number of CPUs in this processor set.
`pset.sys_id`	`int64`	System-assigned processor set ID.
`pset.temporary`	`bool`	Markthis processor set as a temporary resource; if true, this processor setcan exist only in the dynamic configuration and cannot be committed toa configuration file.
`pset.type`	`string`	Names resource type; value for all processor sets is`pset`.
`pset.units`	`string`	Identifiesmeaning of size-related properties; value for all processor sets is`population`.
`pset.poold.objectives`	`string`	Specifies thepoold objectives for a pset.

Thepset.comment,pset.max,pset.min,pset.name, andpset.poold.objectives properties are writable; thepset.default,pset.load,pset.size,pset.sys_id,pset.temporary,pset.type, andpset.units properties are not.

Thepset.load property represents the load on a processor set. The lowestvalue for this property is 0. The value ofpset.load increases ina linear fashion with the load on the set, as measured bythe number of jobs in the system run queue.

Thepset.poold.objectives property specifies an objective which is specific to a particularpset. See thesystem.poold.objectives entry for the specification of this property's syntax.

There are two types of objectives that can be set on apset:

locality

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:

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 uninfluenced 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 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. Forexample, if the~ operator is set, the< and> operatorscannot be set. It is possible to set a< and a> operator together; the values will be validated to ensure that they donot 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, offline or interrupts disabled.
`cpu.sys_id`	`int64`	System-assigned processor ID.

Thecpu.comment,cpu.pinned, andcpu.status properties are writeable.

Thecpu.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 thePS_OFFLINE,PS_ONLINE, andPS_NOINTRmacros.

INTERFACES

The shared objectlibpool.so.1 provides the public interfaces defined below. SeeIntro(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`

Files

/usr/lib/libpool.so.1: shared object
/usr/lib/64/libpool.so.1: 64-bit shared object

Attributes

Seeattributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	system/resource-mgmt/resource-pools
CSI	Enabled
Interface Stability	Uncommitted
MT-Level	Safe

Notes

Functions inlibpool can be used to manipulate static configurations even whenthe pools facility is not enabled. Seepooladm(1M) andpool_set_status(3POOL) for moreinformation about enabling the pools facility. The pools facility must be enabled,however, to modify the dynamic configuration.

Since the Resource Pools facility is ansmf(5) service, it can alsobe enabled and disabled using the standard Service Management Facility (SMF) interfaces.

Skip Navigation Links
Exit Print View
	man pages section 3: Library Interfaces and Headers Oracle Solaris 11 Information Library