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