Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
libpool(3LIB)							 libpool(3LIB)

       libpool - pool configuration manipulation library

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

       The  functions  in  this	 library  define the interface for reading and
       writing resource	pools configuration files, as well as that for commit-
       ing  an existing	configuration 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 abstraction called	a pool.	Processor sets and other enti-
       ties  can  be configured, grouped, and labelled in a persistent fashion
       such that workload components can be associated with a subset of	a sys-
       tem's  total  resources.	 The libpool library provides a	C language API
       for accessing this functionality, while pooladm(1M), poolbind(1M),  and
       poolcfg(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 pset resources for processor sets.

       When  the  pools	 facility  is enabled on a system, the behavior	of the
       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  ar-
       bitrary collection of named, typed properties associated	with it. Prop-
       erties supported	by the pools framework are listed, with	 descriptions,
       under each entity below.	 In general, resource properties can be	one of
       five types: boolean (bool), signed (int64) and unsigned (uint64)	 inte-
       gers, floating point (double), and string values.

       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 com-
       ment field is not used by the default pools  commands,  except  when  a
       configuration is	initiated by the poolcfg utility, in which case	an in-
       formative message is placed in the  system.comment  property  for  that

       Property	name		       Type	  Description
       system.allocate-method	       string	  Allocation  method  to  use when
						  this configuration is	 instanti-
       system.bind-default	       bool	  If  specified	 pool  not  found,
						  bind to pool with 'pool.default'
						  property set to true

       system.comment		       string	  User description of system		       string	  User name for	the configuration
       system.version		       int64	  libpool  version required to ma-
						  nipulate this	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.

       The system.allocate-method, system.bind-default,	 system.comment,  sys-,   system.poold.log-level,   system.poold.log-location,	  sys-
       tem.poold.history-file,	 system.poold.monitor-interval,	   and	  sys-
       tem.poold.objectives  properties	are writable; the system.version prop-
       erty is not.

       The system.allocate-method property accepts only	 two  values,  "impor-
       tance based" and	"surplus to default". The default value	for this prop-
       erty 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  <pool.h>  as

       If  "importance	based" allocation is defined, then during a commit the
       library will allocate resources to pools	using an  algorithm  that  ob-
       serves  minimum	and maximum constraints	for resources but favors those
       resources with greater importance.

       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.

       The system.bind-default property	defaults to true. This property	inter-
       acts  with the project.pool resource control to specify the binding be-
       havior for processes associated with a project. If project.pool is  not
       specified,  then	this property has no effect. If	project.pool is	speci-
       fied 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  mem-
       ber.  If	 system.bind-default is	true, then the project member is bound
       to the default pool (identified as the pool for which  pool.default  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.

       The  various  poold  properties	are used to configure the operation of

       The system.poold.log-level property is used to specify the level	of de-
       tail  provided  in  log	messages.  Valid values	are: ALERT, CRIT, ERR,

       ALERT provides the least	level of detail, DEBUG the greatest. See  sys-
       log(3C)	for  more information about the	meaning	of these debug levels.
       If this property	is not specified, the default value NOTICE is used.

       The system.poold.log-location property is used to specify the  location
       of the logfiles generated by poold. The special value of	"syslog" indi-
       cates that logged messages should be written to syslog(). If this prop-
       erty is not specified, the default location /var/log/pool is used.

       The  system.poold.history-file  specifies  the location of the decision
       history file which is used by poold to improve the quality of its deci-
       sion  making  over time.	If this	property is not	specified, the default
       location	/var/adm/pool is used.

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

       The  system.poold.objectives  property specifies	any system wide	objec-
       tives. An objectives property has the following syntax:

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

       All objectives are prefixed with	an optional importance.	The importance
       acts  as	a multiplier for the objective and thus	increases the signifi-
       cance of	its contribution to the	objective function evaluation.	If  no
       importance is specified,	the default value is 1.

       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 re-
       sources 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  proper-
       ties and	would like the DRP to manipulate resources freely within those

       Property	name	    Type	Description	    bool	Mark this pool as active, if true.
       pool.comment	    string	User description of pool.
       pool.default	    bool	Mark  this  pool  as  the  default
					pool, if true; see system.bind-de-
					fault property.
       pool.importance	    int64	Relative importance of this  pool;
					for possible resource dispute res-
					olution.	    string	User name for pool; used  by  set-
					project(3PROJECT)   as	value  for
					'project.pool'	project	 attribute
					in project(4) database.
       pool.scheduler	    string	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
       pool.sys_id	    int64	System-assigned	pool ID.

       The pool.default	and pool.sys_id	properties are not writable; all other
       listed properties are writable.

       If  pool.scheduler  is specified, it must be set	to the name of a valid
       scheduling class	for the	system.	See the	-c option for priocntl(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	default	processor set.
       pset.load	       uint64	  The load for this processor set.
       pset.max		       uint64	  Maximum  number of CPUs permitted
					  in this processor set.

       pset.min		       uint64	  Minimum number of CPUs  permitted
					  in this processor set.	       string	  User name for	resource.
       pset.size	       uint64	  Current  number  of  CPUs in this
					  processor set.
       pset.sys_id	       int64	  System-assigned processor set	ID.
       pset.type	       string	  Names	resource  type;	 value	for
					  all processor	sets is	pset.
       pset.units	       string	  Identifies  meaning  of  size-re-
					  lated	properties; value  for	all
					  processor sets is population.
       pset.poold.objectives   string	  Specifies  the  poold	 objectives
					  for a	pset.

       The pset.comment, pset.max, pset.min,,	and  pset.poold.objec-
       tives  properties are writable; the pset.default, pset.load, pset.size,
       pset.sys_id, pset.type, and pset.units properties are not.

       The pset.load property represents the load on a processor set. The low-
       est value for this property is 0. The value of pset.load	increases in a
       linear fashion with the load on the set,	as measured by the  number  of
       jobs in the system run queue.

       The pset.poold.objectives property specifies an objective which is spe-
       cific to	a particular pset. See the system.poold.objectives  entry  for
       the specification of this property's syntax.

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

       locality	       This  objective influences the impact that locality, as
		       measured	by lgroup data,	has upon the chosen configura-
		       tion. 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 uninflu-
				enced by resource locality.

       utilization     This  objective favors configurations that allocate re-
		       sources 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	speci-
		fied 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. For example, if
       the  ~ operator is set, the < and > operators cannot be set. It is pos-
       sible to	set a <	and a >	operator together; the values  will  be	 vali-
       dated to	ensure that they do not	overlap.

       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, off-
					  line or interrupts disabled.
       cpu.sys_id	    int64	  System-assigned processor ID.

       The cpu.comment,	cpu.pinned, and	cpu.status properties are writeable.

       The cpu.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	the PS_OFFLINE,	PS_ON-
       LINE, and PS_NOINTR macros.

       The  shared  object	provides the public interfaces defined
       below. See intro(3) for additional information on shared	object	inter-

       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_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

       /usr/lib/		       shared object

       /usr/lib/64/		       64-bit shared object

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWpool (32-bit)		   |
       |			     |SUNWpoolx	(64-bit)	   |
       |CSI			     |Enabled			   |
       |Interface Stability	     |Unstable			   |
       |MT-Level		     |Safe			   |

       intro(3),       pool_component_info(3POOL),	pool_conf_open(3POOL),
       pool_conf_to_elem(3POOL),    pool_create(3POOL),	    pool_error(3POOL),
       pool_get_binding(3POOL),	    pool_get_property(3POOL),	  pool_get_re-
       source(3POOL),  pool_resource_create(3POOL),   pool_value_alloc(3POOL),
       pool_walk_pools(3POOL), attributes(5)

       Functions  in  libpool  can be used to manipulate static	configurations
       even when the pools  facility  is  not  enabled.	 See  pooladm(1M)  and
       pool_set_status(3POOL)  for  more  information about enabling the pools
       facility. The pools facility must be enabled, however,  to  modify  the
       dynamic configuration.

				  18 Sep 2005			 libpool(3LIB)


Want to link to this manual page? Use this URL:

home | help