1 LIBPOOL(3LIB) Interface Libraries LIBPOOL(3LIB) 2 3 4 5 NAME 6 libpool - pool configuration manipulation library 7 8 SYNOPSIS 9 cc [ flag... ] file... -lpool [ library... ] 10 #include <pool.h> 11 12 13 DESCRIPTION 14 The functions in this library define the interface for reading and 15 writing resource pools configuration files, as well as that for 16 committing an existing configuration to becoming the running OS 17 configuration (with respect to partitioning subsystems). The <pool.h> 18 header provides type and function declarations for all library 19 services. 20 21 22 The resource pools facility brings together process-bindable resources 23 into a common abstraction called a pool. Processor sets and other 24 entities can be configured, grouped, and labelled in a persistent 25 fashion such that workload components can be associated with a subset 26 of a system's total resources. The libpool library provides a C 27 language API for accessing this functionality, while pooladm(1M), 28 poolbind(1M), and poolcfg(1M) make this facility available through 29 command invocations from a shell. Each of those manual pages describes 30 aspects of the pools facility; this page describes the properties 31 available to the various entities managed within the pools facility. 32 These entities include the system, pools, and the pset resources for 33 processor sets. 34 35 36 When the pools facility is enabled on a system, the behavior of the 37 following functions is modified. 38 39 40 41 42 System Call Error Value 43 ------------------------------------------- 44 pset_assign(pset !=PS_QUERY) ENOTSUP 45 pset_bind(pset !=PS_QUERY) ENOTSUP 46 pset_create() ENOTSUP 47 pset_destroy() ENOTSUP 48 pset_setattr() ENOTSUP 49 50 51 52 Each active entity within the resource pools framework can have an 53 arbitrary collection of named, typed properties associated with it. 54 Properties supported by the pools framework are listed, with 55 descriptions, under each entity below. In general, resource properties 56 can be one of five types: boolean (bool), signed (int64) and unsigned 57 (uint64) integers, floating point (double), and string values. 58 59 60 All entities and resources support a string property for commenting 61 purposes; this property is available for use by management applications 62 to record descriptions and other administrator oriented data. The 63 comment field is not used by the default pools commands, except when a 64 configuration is initiated by the poolcfg utility, in which case an 65 informative message is placed in the system.comment property for that 66 configuration. 67 68 System 69 70 Property name Type Description 71 system.allocate-method string Allocation method to use when 72 this configuration is 73 instantiated 74 system.bind-default bool If specified pool not found, 75 bind to pool with 'pool.default' 76 property set to true 77 system.comment string User description of system 78 system.name string User name for the configuration 79 system.version int64 libpool version required to 80 manipulate this configuration 81 system.poold.log-level string poold logging level 82 system.poold.log-location string poold logging location 83 system.poold.history-file string poold decision history location 84 system.poold.monitor-interval uint64 poold monitoring sample interval 85 system.poold.objectives string poold objectives for a system. 86 87 88 89 The system.allocate-method, system.bind-default, system.comment, 90 system.name, system.poold.log-level, system.poold.log-location, 91 system.poold.history-file, system.poold.monitor-interval, and 92 system.poold.objectives properties are writable; the system.version 93 property is not. 94 95 96 The system.allocate-method property accepts only two values, 97 "importance based" and "surplus to default". The default value for this 98 property is "importance based". The property is optional and if it is 99 not present the library will allocate resources as though it were 100 present and had the default value. These strings are defined in 101 <pool.h> as POA_IMPORTANCE and POA_SURPLUS_TO_DEFAULT. 102 103 104 If "importance based" allocation is defined, then during a commit the 105 library will allocate resources to pools using an algorithm that 106 observes minimum and maximum constraints for resources but favors those 107 resources with greater importance. 108 109 110 If "surplus to default" is defined, then during a commit the library 111 will allocate minimum resources to all resource sets apart from default 112 which will receive any surplus. 113 114 115 The system.bind-default property defaults to true. This property 116 interacts with the project.pool resource control to specify the binding 117 behavior for processes associated with a project. If project.pool is 118 not specified, then this property has no effect. If project.pool is 119 specified and the specified pool exists, this property has no effect. 120 If the specified pool does not exist, perhaps because of a 121 reconfiguration, then this property controls the binding behavior for 122 the project member. If system.bind-default is true, then the project 123 member is bound to the default pool (identified as the pool for which 124 pool.default is true); otherwise the project member is refused access 125 to the system. Care should be taken with the pools configuration if 126 this property is set to false, so as to avoid denying users access to 127 the system. 128 129 130 The various poold properties are used to configure the operation of 131 poold(1M). 132 133 134 The system.poold.log-level property is used to specify the level of 135 detail provided in log messages. Valid values are: ALERT, CRIT, ERR, 136 WARNING, NOTICE, INFO, and DEBUG. 137 138 139 ALERT provides the least level of detail, DEBUG the greatest. See 140 syslog(3C) for more information about the meaning of these debug 141 levels. If this property is not specified, the default value NOTICE is 142 used. 143 144 145 The system.poold.log-location property is used to specify the location 146 of the logfiles generated by poold. The special value of "syslog" 147 indicates that logged messages should be written to syslog(). If this 148 property is not specified, the default location /var/log/pool is used. 149 150 151 The system.poold.history-file specifies the location of the decision 152 history file which is used by poold to improve the quality of its 153 decision making over time. If this property is not specified, the 154 default location /var/adm/pool is used. 155 156 157 The system.poold.monitor-interval property specifies the monitoring 158 interval (in milliseconds) to be used by poold when sampling 159 utilization statistics. If this property is not specified, the default 160 value of 15 seconds is used. 161 162 163 The system.poold.objectives property specifies any system wide 164 objectives. An objectives property has the following syntax: 165 166 objectives = objective [; objective]* 167 objective = [n:] keyword [op] [value] 168 169 170 171 All objectives are prefixed with an optional importance. The importance 172 acts as a multiplier for the objective and thus increases the 173 significance of its contribution to the objective function evaluation. 174 If no importance is specified, the default value is 1. 175 176 177 The "wt-load" objective is the only objective to which a system element 178 can be set. This objective favors configurations that match resource 179 allocations to resource utilization. A resource set that uses more 180 resources will be given more resources when this objective is active. 181 An administrator should use this objective when he is relatively 182 satisfied with the constraints established using the minimum and 183 maximum properties and would like the DRP to manipulate resources 184 freely within those constraints. 185 186 Pools 187 188 Property name Type Description 189 pool.active bool Mark this pool as active, if true. 190 pool.comment string User description of pool. 191 pool.default bool Mark this pool as the default 192 pool, if true; see 193 system.bind-default property. 194 pool.importance int64 Relative importance of this pool; 195 for possible resource dispute 196 resolution. 197 pool.name string User name for pool; used by 198 setproject(3PROJECT) as value for 199 'project.pool' project attribute 200 in project(4) database. 201 pool.scheduler string Scheduler class to which consumers 202 of this pool will be bound. This 203 property is optional and if not 204 specified, the scheduler bindings 205 for consumers of this pool are not 206 affected. 207 pool.sys_id int64 System-assigned pool ID. 208 pool.temporary bool Mark this pool as a temporary 209 resource; if true, this pool can 210 exist only in the dynamic 211 configuration and cannot be 212 committed to a configuration file. 213 214 215 216 The pool.default, pool.sys_id, and pool.temporary properties are not 217 writable; all other listed properties are writable. 218 219 220 If pool.scheduler is specified, it must be set to the name of a valid 221 scheduling class for the system. See the -c option for priocntl(1) for 222 a list of valid class names. 223 224 Processor Sets 225 226 Property name Type Description 227 pset.comment string User description of resource. 228 pset.default bool Marks default processor set. 229 pset.load uint64 The load for this processor set. 230 pset.max uint64 Maximum number of CPUs permitted 231 in this processor set. 232 pset.min uint64 Minimum number of CPUs permitted 233 in this processor set. 234 pset.name string User name for resource. 235 pset.size uint64 Current number of CPUs in this 236 processor set. 237 pset.sys_id int64 System-assigned processor set ID. 238 pset.temporary bool Mark this processor set as a 239 temporary resource; if true, this 240 processor set can exist only in 241 the dynamic configuration and 242 cannot be committed to a 243 configuration file. 244 pset.type string Names resource type; value for 245 all processor sets is pset. 246 pset.units string Identifies meaning of 247 size-related properties; value 248 for all processor sets is 249 population. 250 pset.poold.objectives string Specifies the poold objectives 251 for a pset. 252 253 254 255 The pset.comment, pset.max, pset.min, pset.name, and 256 pset.poold.objectives properties are writable; the pset.default, 257 pset.load, pset.size, pset.sys_id, pset.temporary, pset.type, and 258 pset.units properties are not. 259 260 261 The pset.load property represents the load on a processor set. The 262 lowest value for this property is 0. The value of pset.load increases 263 in a linear fashion with the load on the set, as measured by the number 264 of jobs in the system run queue. 265 266 267 The pset.poold.objectives property specifies an objective which is 268 specific to a particular pset. See the system.poold.objectives entry 269 for the specification of this property's syntax. 270 271 272 There are two types of objectives that can be set on a pset: 273 274 locality 275 This objective influences the impact that locality, as 276 measured by lgroup data, has upon the chosen 277 configuration. This objective can take one of three 278 values: 279 280 tight 281 If set, configurations that maximize resource 282 locality are favored. 283 284 285 loose 286 If set, configurations that minimize resource 287 locality are favored. 288 289 290 none 291 This is the default value for this objective. 292 If set, configuration favorability is 293 uninfluenced by resource locality. 294 295 296 297 utilization 298 This objective favors configurations that allocate 299 resources to partitions that are failing to preserve the 300 specified utilization objective. 301 302 303 304 These objectives are specified in terms of an operator and a value. The 305 operators are 306 307 < 308 The ``less than'' operator is used to indicate that the specified 309 value should be treated as a maximum target value. 310 311 312 > 313 The ``greater than'' operator is used to indicate that the 314 specified value should be treated as a minimum target value. 315 316 317 ~ 318 The ``about'' operator is used to indicate that the specified 319 value should be treated as a target value about which some 320 fluctuation is acceptable. 321 322 323 324 Only one objective of each type of operator can be set. For example, if 325 the ~ operator is set, the < and > operators cannot be set. It is 326 possible to set a < and a > operator together; the values will be 327 validated to ensure that they do not overlap. 328 329 Processors 330 331 Property name Type Description 332 ----------------------------------------------------------- 333 cpu.comment string User description of CPU. 334 cpu.pinned bool CPU pinned to this processor set. 335 cpu.status int64 Processor status, on-line, 336 offline or interrupts disabled. 337 cpu.sys_id int64 System-assigned processor ID. 338 339 340 341 The cpu.comment, cpu.pinned, and cpu.status properties are writable. 342 343 344 The cpu.status property can be set only to the following values: 345 346 off-line 347 Set the CPU offline. 348 349 350 on-line 351 Set the CPU online. 352 353 354 no-intr 355 Disable interrupt processing on the CPU. 356 357 358 359 These values are defined in <sys/processor.h> as the PS_OFFLINE, 360 PS_ONLINE, and PS_NOINTR macros. 361 362 INTERFACES 363 The shared object libpool.so.1 provides the public interfaces defined 364 below. See Intro(3) for additional information on shared object 365 interfaces. 366 367 368 369 370 pool_associate pool_component_info 371 pool_component_to_elem pool_conf_alloc 372 pool_conf_close pool_conf_commit 373 pool_conf_export pool_conf_free 374 pool_conf_info pool_conf_location 375 pool_conf_open pool_conf_remove 376 pool_conf_rollback pool_conf_status 377 pool_conf_to_elem pool_conf_update 378 pool_conf_validate pool_create 379 pool_destroy pool_dissociate 380 pool_dynamic_location pool_error 381 pool_get_binding pool_get_owning_resource 382 pool_get_pool pool_get_property 383 pool_get_resource pool_get_resource_binding 384 pool_get_status pool_info 385 pool_put_property pool_query_components 386 pool_query_pool_resources pool_query_pools 387 pool_query_resource_components pool_query_resources 388 pool_resource_create pool_resource_destroy 389 pool_resource_info pool_resource_to_elem 390 pool_resource_transfer pool_resource_type_list 391 pool_resource_xtransfer pool_rm_property 392 pool_set_binding pool_set_status 393 pool_static_location pool_strerror 394 pool_to_elem pool_value_alloc 395 pool_value_free pool_value_get_bool 396 pool_value_get_double pool_value_get_int64 397 pool_value_get_name pool_value_get_string 398 pool_value_get_type pool_value_get_uint64 399 pool_value_set_bool pool_value_set_double 400 pool_value_set_int64 pool_value_set_name 401 pool_value_set_string pool_value_set_uint64 402 pool_version pool_walk_components 403 pool_walk_pools pool_walk_properties 404 pool_walk_resources 405 406 407 FILES 408 /usr/lib/libpool.so.1 409 shared object 410 411 412 /usr/lib/64/libpool.so.1 413 64-bit shared object 414 415 416 ATTRIBUTES 417 See attributes(5) for descriptions of the following attributes: 418 419 420 421 422 +--------------------+-----------------+ 423 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 424 +--------------------+-----------------+ 425 |CSI | Enabled | 426 +--------------------+-----------------+ 427 |Interface Stability | Unstable | 428 +--------------------+-----------------+ 429 |MT-Level | Safe | 430 +--------------------+-----------------+ 431 432 SEE ALSO 433 Intro(3), pool_component_info(3POOL), pool_conf_open(3POOL), 434 pool_conf_to_elem(3POOL), pool_create(3POOL), pool_error(3POOL), 435 pool_get_binding(3POOL), pool_get_property(3POOL), 436 pool_get_resource(3POOL), pool_resource_create(3POOL), 437 pool_value_alloc(3POOL), pool_walk_pools(3POOL), attributes(5), smf(5) 438 439 NOTES 440 Functions in libpool can be used to manipulate static configurations 441 even when the pools facility is not enabled. See pooladm(1M) and 442 pool_set_status(3POOL) for more information about enabling the pools 443 facility. The pools facility must be enabled, however, to modify the 444 dynamic configuration. 445 446 447 Since the Resource Pools facility is an smf(5) service, it can also be 448 enabled and disabled using the standard Service Management Facility 449 (SMF) interfaces. 450 451 452 453 August 19, 2019 LIBPOOL(3LIB)