1libpool(3LIB) Interface Libraries libpool(3LIB)
2
6 libpool - pool configuration manipulation library
7
9 cc [ flag... ] file... [ library... ]
10 #include <pool.h>
11
14 The functions in this library define the interface for reading and
15 writing resource pools configuration files, as well as that for commit‐
16 ing an existing configuration to becoming the running OS configuration
17 (with respect to partitioning subsystems). The <pool.h> header provides
18 type and function declarations for all library services.
19 The resource pools facility brings together process-bindable resources
22 into a common abstraction called a pool. Processor sets and other enti‐
23 ties can be configured, grouped, and labelled in a persistent fashion
24 such that workload components can be associated with a subset of a sys‐
25 tem's total resources. The libpool library provides a C language API
26 for accessing this functionality, while pooladm(1M), poolbind(1M), and
27 poolcfg(1M) make this facility available through command invocations
28 from a shell. Each of those manual pages describes aspects of the pools
29 facility; this page describes the properties available to the various
30 entities managed within the pools facility. These entities include the
31 system, pools, and the pset resources for processor sets.
32 When the pools facility is enabled on a system, the behavior of the
35 following functions is modified.
36 System Call Error Value
41 ───────────────────────────────────────────────────────────
42 pset_assign(pset !=PS_QUERY) ENOTSUP
43 pset_bind(pset !=PS_QUERY) ENOTSUP
44 pset_create() ENOTSUP
45 pset_destroy() ENOTSUP
46 pset_setattr() ENOTSUP
47 Each active entity within the resource pools framework can have an
51 arbitrary collection of named, typed properties associated with it.
52 Properties supported by the pools framework are listed, with descrip‐
53 tions, under each entity below. In general, resource properties can be
54 one of five types: boolean (bool), signed (int64) and unsigned (uint64)
55 integers, floating point (double), and string values.
56 All entities and resources support a string property for commenting
59 purposes; this property is available for use by management applications
60 to record descriptions and other administrator oriented data. The com‐
61 ment field is not used by the default pools commands, except when a
62 configuration is initiated by the poolcfg utility, in which case an
63 informative message is placed in the system.comment property for that
64 configuration.
65 System
67 Property name Type Description
68 system.allocate-method string Allocation method to use when
70 this configuration is instanti‐
71 ated
72 system.bind-default bool If specified pool not found,
73 bind to pool with 'pool.default'
74 property set to true
75 system.comment string User description of system
76 system.name string User name for the configuration
77 system.version int64 libpool version required to
78 manipulate this configuration
79 system.poold.log-level string poold logging level
80 system.poold.log-location string poold logging location
81 system.poold.history-file string poold decision history location
82 system.poold.monitor-interval uint64 poold monitoring sample interval
83 system.poold.objectives string poold objectives for a system.
84 The system.allocate-method, system.bind-default, system.comment, sys‐
88 tem.name, system.poold.log-level, system.poold.log-location, sys‐
89 tem.poold.history-file, system.poold.monitor-interval, and sys‐
90 tem.poold.objectives properties are writable; the system.version prop‐
91 erty is not.
92 The system.allocate-method property accepts only two values, "impor‐
95 tance based" and "surplus to default". The default value for this prop‐
96 erty is "importance based". The property is optional and if it is not
97 present the library will allocate resources as though it were present
98 and had the default value. These strings are defined in <pool.h> as
99 POA_IMPORTANCE and POA_SURPLUS_TO_DEFAULT.
100 If "importance based" allocation is defined, then during a commit the
103 library will allocate resources to pools using an algorithm that
104 observes minimum and maximum constraints for resources but favors those
105 resources with greater importance.
106 If "surplus to default" is defined, then during a commit the library
109 will allocate minimum resources to all resource sets apart from default
110 which will receive any surplus.
111 The system.bind-default property defaults to true. This property inter‐
114 acts with the project.pool resource control to specify the binding
115 behavior for processes associated with a project. If project.pool is
116 not specified, then this property has no effect. If project.pool is
117 specified and the specified pool exists, this property has no effect.
118 If the specified pool does not exist, perhaps because of a reconfigura‐
119 tion, then this property controls the binding behavior for the project
120 member. If system.bind-default is true, then the project member is
121 bound to the default pool (identified as the pool for which
122 pool.default is true); otherise the project member is refused access to
123 the system. Care should be taken with the pools configuration if this
124 property is set to false, so as to avoid denying users access to the
125 system.
126 The various poold properties are used to configure the operation of
129 poold(1M).
130 The system.poold.log-level property is used to specify the level of
133 detail provided in log messages. Valid values are: ALERT, CRIT, ERR,
134 WARNING, NOTICE, INFO, and DEBUG.
135 ALERT provides the least level of detail, DEBUG the greatest. See sys‐
138 log(3C) for more information about the meaning of these debug levels.
139 If this property is not specified, the default value NOTICE is used.
140 The system.poold.log-location property is used to specify the location
143 of the logfiles generated by poold. The special value of "syslog" indi‐
144 cates that logged messages should be written to syslog(). If this prop‐
145 erty is not specified, the default location /var/log/pool is used.
146 The system.poold.history-file specifies the location of the decision
149 history file which is used by poold to improve the quality of its deci‐
150 sion making over time. If this property is not specified, the default
151 location /var/adm/pool is used.
152 The system.poold.monitor-interval property specifies the monitoring
155 interval (in milliseconds) to be used by poold when sampling utiliza‐
156 tion statistics. If this property is not specified, the default value
157 of 15 seconds is used.
158 The system.poold.objectives property specifies any system wide objec‐
161 tives. An objectives property has the following syntax:
162 objectives = objective [; objective]*
164 objective = [n:] keyword [op] [value]
165 All objectives are prefixed with an optional importance. The importance
169 acts as a multiplier for the objective and thus increases the signifi‐
170 cance of its contribution to the objective function evaluation. If no
171 importance is specified, the default value is 1.
172 The "wt-load" objective is the only objective to which a system element
175 can be set. This objective favors configurations that match resource
176 allocations to resource utilization. A resource set that uses more
177 resources will be given more resources when this objective is active.
178 An administrator should use this objective when he is relatively satis‐
179 fied with the constraints established using the minimum and maximum
180 properties and would like the DRP to manipulate resources freely within
181 those constraints.
182 Pools
184 Property name Type Description
185 pool.active bool Mark this pool as active, if true.
186 pool.comment string User description of pool.
187 pool.default bool Mark this pool as the default
188 pool, if true; see system.bind-
189 default property.
190 pool.importance int64 Relative importance of this pool;
191 for possible resource dispute res‐
192 olution.
193 pool.name string User name for pool; used by set‐
194 project(3PROJECT) as value for
195 'project.pool' project attribute
196 in project(4) database.
197 pool.scheduler string Scheduler class to which consumers
198 of this pool will be bound. This
199 property is optional and if not
200 specified, the scheduler bindings
201 for consumers of this pool are not
202 affected.
203 pool.sys_id int64 System-assigned pool ID.
204 pool.temporary bool Mark this pool as a temporary
206 resource; if true, this pool can
207 exist only in the dynamic configu‐
208 ration and cannot be committed to
209 a configuration file.
210 The pool.default, pool.sys_id, and pool.temporary properties are not
214 writable; all other listed properties are writable.
215 If pool.scheduler is specified, it must be set to the name of a valid
218 scheduling class for the system. See the -c option for priocntl(1) for
219 a list of valid class names.
220 Processor Sets
222 Property name Type Description
223 pset.comment string User description of resource.
224 pset.default bool Marks default processor set.
225 pset.load uint64 The load for this processor set.
226 pset.max uint64 Maximum number of CPUs permitted
227 in this processor set.
228 pset.min uint64 Minimum number of CPUs permitted
229 in this processor set.
230 pset.name string User name for resource.
231 pset.size uint64 Current number of CPUs in this
232 processor set.
233 pset.sys_id int64 System-assigned processor set ID.
234 pset.temporary bool Mark this processor set as a tem‐
235 porary resource; if true, this
236 processor set can exist only in
237 the dynamic configuration and
238 cannot be committed to a configu‐
239 ration file.
240 pset.type string Names resource type; value for
241 all processor sets is pset.
242 pset.units string Identifies meaning of size-
243 related properties; value for all
244 processor sets is population.
245 pset.poold.objectives string Specifies the poold objectives
246 for a pset.
247 The pset.comment, pset.max, pset.min, pset.name, and pset.poold.objec‐
251 tives properties are writable; the pset.default, pset.load, pset.size,
252 pset.sys_id, pset.temporary, pset.type, and pset.units properties are
253 not.
254 The pset.load property represents the load on a processor set. The low‐
257 est value for this property is 0. The value of pset.load increases in a
258 linear fashion with the load on the set, as measured by the number of
259 jobs in the system run queue.
260 The pset.poold.objectives property specifies an objective which is spe‐
263 cific to a particular pset. See the system.poold.objectives entry for
264 the specification of this property's syntax.
265 There are two types of objectives that can be set on a pset:
268 locality This objective influences the impact that locality, as
270 measured by lgroup data, has upon the chosen configura‐
271 tion. This objective can take one of three values:
272 tight If set, configurations that maximize resource
274 locality are favored.
275 loose If set, configurations that minimize resource
278 locality are favored.
279 none This is the default value for this objective.
282 If set, configuration favorability is uninflu‐
283 enced by resource locality.
284 utilization This objective favors configurations that allocate
288 resources to partitions that are failing to preserve the
289 specified utilization objective.
290 These objectives are specified in terms of an operator and a value. The
294 operators are
295 < The ``less than'' operator is used to indicate that the specified
297 value should be treated as a maximum target value.
298 > The ``greater than'' operator is used to indicate that the speci‐
301 fied value should be treated as a minimum target value.
302 ~ The ``about'' operator is used to indicate that the specified
305 value should be treated as a target value about which some fluctu‐
306 ation is acceptable.
307 Only one objective of each type of operator can be set. For example, if
311 the ~ operator is set, the < and > operators cannot be set. It is pos‐
312 sible to set a < and a > operator together; the values will be vali‐
313 dated to ensure that they do not overlap.
314 Processors
316 Property name Type Description
317 ─────────────────────────────────────────────────────────────────────
318 cpu.comment string User description of CPU.
319 cpu.pinned bool CPU pinned to this processor set.
320 cpu.status int64 Processor status, on-line, off‐
321 line or interrupts disabled.
322 cpu.sys_id int64 System-assigned processor ID.
323 The cpu.comment, cpu.pinned, and cpu.status properties are writeable.
327 The cpu.status property can be set only to the following values:
330 off-line Set the CPU offline.
332 on-line Set the CPU online.
335 no-intr Disable interrupt processing on the CPU.
338 These values are defined in <sys/processor.h> as the PS_OFFLINE,
342 PS_ONLINE, and PS_NOINTR macros.
343
345 The shared object libpool.so.1 provides the public interfaces defined
346 below. See Intro(3) for additional information on shared object inter‐
347 faces.
348 pool_associate pool_component_info
353 pool_component_to_elem pool_conf_alloc
354 pool_conf_close pool_conf_commit
355 pool_conf_export pool_conf_free
356 pool_conf_info pool_conf_location
357 pool_conf_open pool_conf_remove
358 pool_conf_rollback pool_conf_status
359 pool_conf_to_elem pool_conf_update
360 pool_conf_validate pool_create
361 pool_destroy pool_dissociate
362 pool_dynamic_location pool_error
363 pool_get_binding pool_get_owning_resource
364 pool_get_pool pool_get_property
365 pool_get_resource pool_get_resource_binding
366 pool_get_status pool_info
367 pool_put_property pool_query_components
368 pool_query_pool_resources pool_query_pools
369 pool_query_resource_components pool_query_resources
370 pool_resource_create pool_resource_destroy
371 pool_resource_info pool_resource_to_elem
372 pool_resource_transfer pool_resource_type_list
373 pool_resource_xtransfer pool_rm_property
374 pool_set_binding pool_set_status
375 pool_static_location pool_strerror
376 pool_to_elem pool_value_alloc
377 pool_value_free pool_value_get_bool
378 pool_value_get_double pool_value_get_int64
379 pool_value_get_name pool_value_get_string
380 pool_value_get_type pool_value_get_uint64
381 pool_value_set_bool pool_value_set_double
382 pool_value_set_int64 pool_value_set_name
383 pool_value_set_string pool_value_set_uint64
384 pool_version pool_walk_components
385 pool_walk_pools pool_walk_properties
386 pool_walk_resources
387
390 /usr/lib/libpool.so.1 shared object
391 /usr/lib/64/libpool.so.1 64-bit shared object
394
397 See attributes(5) for descriptions of the following attributes:
398 ┌─────────────────────────────┬─────────────────────────────┐
403 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
404 ├─────────────────────────────┼─────────────────────────────┤
405 │Availability │SUNWpool (32-bit) │
406 ├─────────────────────────────┼─────────────────────────────┤
407 │ │SUNWpoolx (64-bit) │
408 ├─────────────────────────────┼─────────────────────────────┤
409 │CSI │Enabled │
410 ├─────────────────────────────┼─────────────────────────────┤
411 │Interface Stability │Unstable │
412 ├─────────────────────────────┼─────────────────────────────┤
413 │MT-Level │Safe │
414 └─────────────────────────────┴─────────────────────────────┘
415
417 Intro(3), pool_component_info(3POOL), pool_conf_open(3POOL),
418 pool_conf_to_elem(3POOL), pool_create(3POOL), pool_error(3POOL),
419 pool_get_binding(3POOL), pool_get_property(3POOL),
420 pool_get_resource(3POOL), pool_resource_create(3POOL),
421 pool_value_alloc(3POOL), pool_walk_pools(3POOL), attributes(5), smf(5)
422
424 Functions in libpool can be used to manipulate static configurations
425 even when the pools facility is not enabled. See pooladm(1M) and
426 pool_set_status(3POOL) for more information about enabling the pools
427 facility. The pools facility must be enabled, however, to modify the
428 dynamic configuration.
429 Since the Resource Pools facility is an smf(5) service, it can also be
432 enabled and disabled using the standard Service Management Facility
433 (SMF) interfaces.
434SunOS 5.11 14 Dec 2006 libpool(3LIB)