libpool man page on SmartOS

Printed from http://www.polarhome.com/service/man/?qf=libpool&af=0&tf=2&of=SmartOS

LIBPOOL(3LIB)							 LIBPOOL(3LIB)

NAME
       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
       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
       arbitrary  collection  of  named,  typed properties associated with it.
       Properties supported by the pools framework are listed,	with  descrip‐
       tions, under each entity below.	In general, resource properties can be
       one of five types: boolean (bool), signed (int64) and unsigned (uint64)
       integers, 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
       informative message is placed in the system.comment property  for  that
       configuration.

   System
	       Property name		Type		  Description

       system.allocate-method	       string	Allocation  method  to	use when
						this configuration is  instanti‐
						ated
       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
       system.name		       string	User name for the configuration
       system.version		       int64	libpool	  version   required  to
						manipulate 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‐
       tem.name,   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
       POA_IMPORTANCE and POA_SURPLUS_TO_DEFAULT.

       If  "importance	based" allocation is defined, then during a commit the
       library will allocate  resources	 to  pools  using  an  algorithm  that
       observes 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
       behavior for processes associated with a project.  If  project.pool  is
       not  specified,	then  this  property has no effect. If project.pool is
       specified and the specified pool exists, this property has  no  effect.
       If the specified pool does not exist, perhaps because of a reconfigura‐
       tion, then this property controls the binding behavior for the  project
       member.	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
       poold(1M).

       The  system.poold.log-level  property  is  used to specify the level of
       detail provided in log messages. Valid values are:  ALERT,  CRIT,  ERR,
       WARNING, NOTICE, INFO, and DEBUG.

       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
       interval (in milliseconds) to be used by poold when  sampling  utiliza‐
       tion  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
       resources  will	be given more resources when this objective is active.
       An administrator should use this objective when he is relatively satis‐
       fied  with  the	constraints  established using the minimum and maximum
       properties and would like the DRP to manipulate resources freely within
       those constraints.

   Pools
	Property name	  Type		     Description
       pool.active	 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-
				  default property.
       pool.importance	 int64	  Relative  importance of this pool;
				  for possible resource dispute res‐
				  olution.
       pool.name	 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
				  affected.
       pool.sys_id	 int64	  System-assigned pool ID.

       pool.temporary	 bool	  Mark	this  pool  as	a  temporary
				  resource; if true, this  pool	 can
				  exist only in the dynamic configu‐
				  ration and cannot be committed  to
				  a configuration file.

       The  pool.default,  pool.sys_id,	 and pool.temporary 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.
       pset.name	       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.temporary	       bool	Mark this processor set as a tem‐
					porary resource;  if  true,  this
					processor  set	can exist only in
					the  dynamic  configuration   and
					cannot be committed to a configu‐
					ration file.
       pset.type	       string	Names resource	type;  value  for
					all processor sets is pset.
       pset.units	       string	Identifies   meaning   of   size-
					related 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, pset.name, and  pset.poold.objec‐
       tives  properties are writable; the pset.default, pset.load, pset.size,
       pset.sys_id, pset.temporary, 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
		      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	speci‐
	    fied 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 fluctu‐
	    ation 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.

   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,  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_ONLINE, and PS_NOINTR macros.

INTERFACES
       The shared object libpool.so.1 provides the public  interfaces  defined
       below.  See Intro(3) for additional information on shared object inter‐
       faces.

       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
       pool_walk_resources

FILES
       /usr/lib/libpool.so.1
				   shared object

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

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │CSI		    │ Enabled	      │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Unstable	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       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_resource(3POOL),		  pool_resource_create(3POOL),
       pool_value_alloc(3POOL), pool_walk_pools(3POOL), attributes(5), smf(5)

NOTES
       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.

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

				 Dec 14, 2006			 LIBPOOL(3LIB)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net