Perl Library Functions Lgrp(3PERL)
NAME
Lgrp - Perl interface to Solaris liblgrp library
SYNOPSIS
use Sun::Solaris::Lgrp qw(:ALL);
# initialize lgroup interface
my $cookie = lgrp_init(LGRP_VIEW_OS | LGRP_VIEW_CALLER);
my $l = Sun::Solaris::Lgrp->new(LGRP_VIEW_OS |
LGRP_VIEW_CALLER);
my $version = lgrp_version(LGRP_VER_CURRENT | LGRP_VER_NONE);
$version = $l->version(LGRP_VER_CURRENT | LGRP_VER_NONE);
$home = lgrp_home(P_PID, P_MYID);
$home = l->home(P_PID, P_MYID);
lgrp_affinity_set(P_PID, $pid, $lgrp,
LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE);
$l->affinity_set(P_PID, $pid, $lgrp,
LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE);
my $affinity = lgrp_affinity_get(P_PID, $pid, $lgrp);
$affinity = $l->affinity_get(P_PID, $pid, $lgrp);
my $nlgrps = lgrp_nlgrps($cookie);
$nlgrps = $l->nlgrps();
my $root = lgrp_root($cookie);
$root = l->root();
$latency = lgrp_latency($lgrp1, $lgrp2);
$latency = $l->latency($lgrp1, $lgrp2);
my @children = lgrp_children($cookie, $lgrp);
@children = l->children($lgrp);
my @parents = lgrp_parents($cookie, $lgrp);
@parents = l->parents($lgrp);
my @lgrps = lgrp_lgrps($cookie);
@lgrps = l->lgrps();
@lgrps = lgrp_lgrps($cookie, $lgrp);
@lgrps = l->lgrps($lgrp);
my @leaves = lgrp_leaves($cookie);
@leaves = l->leaves();
my $is_leaf = lgrp_isleaf($cookie, $lgrp);
$is_leaf = $l->is_leaf($lgrp);
SunOS 5.11 Last change: 30 Aug 2006 1
Perl Library Functions Lgrp(3PERL)
my @cpus = lgrp_cpus($cookie, $lgrp,
LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
@cpus = l->cpus($lgrp, LGRP_CONTENT_HIERARCHY |
LGRP_CONTENT_DIRECT);
my $memsize = lgrp_mem_size($cookie, $lgrp,
LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE,
LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
$memsize = l->mem_size($lgrp,
LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE,
LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT);
my $is_stale = lgrp_cookie_stale($cookie);
$stale = l->stale();
lgrp_fini($cookie);
# The following is available for API version greater than 1:
my @lgrps = lgrp_resources($cookie, $lgrp, LGRP_RSRC_CPU);
# Get latencies from cookie
$latency = lgrp_latency_cookie($cookie, $from, $to);
DESCRIPTION
This module provides access to the liblgrp(3LIB) library and to various constants and functions defined ininterface to the library. The procedural interface requires (in most cases) passing around a transparent cookie. The object interface hides all the cookie manipulations from the user. Functions returning a scalar value indicate an error by
. It provides both the procedural and object returning undef. The caller can examine the $! variable to
get the error value.Functions returning a list value return the number of ele-
ments in the list when called in scalar context. In theevent of error, the empty list is returned in the array con-
text and undef is returned in the scalar context. Constants The constants are exported with :CONSTANTS or :ALL tags:use Sun::Solaris::Lgrp ':ALL';
SunOS 5.11 Last change: 30 Aug 2006 2
Perl Library Functions Lgrp(3PERL)
oruse Sun::Solaris::Lgrp ':CONSTANTS';
The following constants are available for use in Perl pro-
grams:LGRP_NONE
LGRP_VER_CURRENT
LGRP_VER_NONE
LGRP_VIEW_CALLER
LGRP_VIEW_OS
LGRP_AFF_NONE
LGRP_AFF_STRONG
LGRP_AFF_WEAK
LGRP_CONTENT_DIRECT
LGRP_CONTENT_HIERARCHY
LGRP_MEM_SZ_FREE
LGRP_MEM_SZ_FREE
LGRP_RSRC_CPU (1)
LGRP_RSRC_MEM (1)
LGRP_CONTENT_ALL (1)
LGRP_LAT_CPU_TO_MEM (1)
P_PID
P_LWPID
P_MYID
(1) Available for versions of the liblgrp(3LIB) API greater than 1. Functions A detailed description of each function follows. Since thismodule is intended to provide a Perl interface to the func-
tions in liblgrp(3LIB), a very short description is givenfor the corresponding functions in this module and a refer-
ence is given to the complete description in the liblgrp manual pages. Any differences or additional functionality in the Perl module are highlighted and fully documented here.lgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS])
This function initializes the lgroup interface and takes a snapshot of the lgroup hierarchy with the given view.Given the view, lgrp_init() returns a cookie represent-
ing this snapshot of the lgroup hierarchy. This cookieshould be used with other routines in the lgroup inter-
face needing the lgroup hierarchy. The lgrp_fini() func-
tion should be called with the cookie when it is nolonger needed. Unlike lgrp_init(3LGRP), LGRP_VIEW_OS is
assumed as the default if no view is provided.SunOS 5.11 Last change: 30 Aug 2006 3
Perl Library Functions Lgrp(3PERL)
Upon successful completion, lgrp_init() returns a
cookie. Otherwise it returns undef and sets $! to indi-
cate the error.See lgrp_init(3LGRP) for more information.
lgrp_fini($cookie)
This function takes a cookie, frees the snapshot of thelgroup hierarchy created by lgrp_init(), and cleans up
anything else set up by lgrp_init(). After this function
is called, the cookie returned by the lgroup interface might no longer be valid and should not be used. Upon successful completion, 1 is returned. Otherwise,undef is returned and $! is set to indicate the error.
See lgrp_fini(3LGRP) for more information.
lgrp_view($cookie)
This function takes a cookie representing the snapshot of the lgroup hierarchy and returns the snapshot's view of the lgroup hierarchy.If the given view is LGRP_VIEW_CALLER, the snapshot con-
tains only the resources that are available to the caller (such as those with respect to processor sets).When the view is LGRP_VIEW_OS, the snapshot contains
what is available to the operating system. Upon succesful completion, the function returns the view for the snapshot of the lgroup hierarchy represented bythe given cookie. Otherwise, undef is returned and $!
is set to indicate the error.See lgrp_view(3LGRP) for more information.
lgrp_home($idtype, $id)
This function returns the home lgroup for the given pro-
cess or thread. The $idtype argument should be P_PID to
specify a process and the $id argument should be its
process ID. Otherwise, the $idtype argument should be
P_LWPID to specify a thread and the $id argument should
be its LWP ID. The value P_MYID can be used for the $id
argument to specify the current process or thread.Upon successful completion, lgrp_home() returns the ID
SunOS 5.11 Last change: 30 Aug 2006 4
Perl Library Functions Lgrp(3PERL)
of the home lgroup of the specified process or thread.Otherwise, undef is returned and $! is set to indicate
the error.See lgrp_home(3LGRP) for more information.
lgrp_cookie_stale($cookie)
Upon successful completion, this function returns whether the cookie is stale. Otherwise, it returns undefand sets $! to indicate the error.
The lgrp_cookie_stale() function will fail with EINVAL
if the cookie is not valid.See lgrp_cookie_stale(3LGRP) for more information.
lgrp_cpus($cookie, $lgrp, $context)
This function takes a cookie representing a snapshot of the lgroup hierarchy and returns the list of CPUs in thelgroup specified by $lgrp. The $context argument should
be set to one of the following values to specify whetherthe direct contents or everything in this lgroup includ-
ing its children should be returned:LGRP_CONTENT_HIERARCHY everything within this hierar-
chyLGRP_CONTENT_DIRECT directly contained in lgroup
When called in scalar context, lgrp_cpus() function
returns the number of CPUs contained in the specified lgroup.In the event of error, undef is returned in scalar con-
text and $! is set to indicate the error. In list con-
text, the empty list is returned and $! is set.
See lgrp_cpus(3LGRP) for more information.
lgrp_children($cookie, $lgrp)
This function takes a cookie representing a snapshot of the lgroup hierarchy and returns the list of lgroups that are children of the specified lgroup.When called in scalar context, lgrp_children() returns
SunOS 5.11 Last change: 30 Aug 2006 5
Perl Library Functions Lgrp(3PERL)
the number of children lgroups for the specified lgroup. In the event of error, undef or empty list is returnedand $! is set to indicate the error.
See lgrp_children(3LGRP) for more information.
lgrp_parents($cookie, $lgrp)
This function takes a cookie representing a snapshot of the lgroup hierarchy and returns the list of parents of the specified lgroup.When called in scalar context, lgrp_parents() returns
the number of parent lgroups for the specified lgroup. In the event of error, undef or an empty list isreturned and $! is set to indicate the error.
See lgrp_parents(3LGRP) for more information.
lgrp_nlgrps($cookie)
This function takes a cookie representing a snapshot of the lgroup hierarchy. It returns the number of lgroups in the hierarchy, where the number is always at least one.In the event of error, undef is returned and $! is set
to EINVAL, indicating that the cookie is not valid.See lgrp_nlgrps(3LGRP) for more information.
lgrp_root($cookie)
This function returns the root lgroup ID.In the event of error, undef is returned and $! is set
to EINVAL, indicatng that the cookie is not valid.See lgrp_root(3LGRP) for more information.
lgrp_mem_size($cookie, $lgrp, $type, $content)
This function takes a cookie representing a snapshot of the lgroup hierarchy. The function returns the memorysize of the given lgroup in bytes. The $type argument
should be set to one of the following values:SunOS 5.11 Last change: 30 Aug 2006 6
Perl Library Functions Lgrp(3PERL)
LGRP_MEM_SZ_FREE free memory
LGRP_MEM_SZ_INSTALLED installed memory
The $content argument should be set to one of the fol-
lowing values to specify whether the direct contents or everything in this lgroup including its children should be returned:LGRP_CONTENT_HIERARCHY Return everything within this
hierarchy.LGRP_CONTENT_DIRECT Return that which is directly
contained in this lgroup. The total sizes include all the memory in the lgroup including its children, while the others reflect only the memory contained directly in the given lgroup. Upon successful completion, the size in bytes isreturned. Otherwise, undef is returned and $! is set to
indicate the error.See lgrp_mem_size(3LGRP) for more information.
lgrp_version([$version])
This function takes an interface version number, $ver-
sion, as an argument and returns an lgroup interfaceversion. The $version argument should be the value of
LGRP_VER_CURRENT or LGRP_VER_NONE to find out the
current lgroup interface version on the running system.If $version is still supported by the implementation,
then lgrp_version() returns the requested version. If
LGRP_VER_NONE is returned, the implementation cannot
support the requested version.If $version is LGRP_VER_NONE, lgrp_version() returns the
current version of the library. The following example tests whether the version of the interface used by the caller is supported:lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or
die("Built with unsupported lgroup interface");See lgrp_version(3LGRP) for more information.
SunOS 5.11 Last change: 30 Aug 2006 7
Perl Library Functions Lgrp(3PERL)
lgrp_affinity_set($idtype, $id, $lgrp, $affinity)
This function sets the affinity that the LWP or set ofLWPs specified by $idtype and $id have for the given
lgroup. The lgroup affinity can be set toLGRP_AFF_STRONG, LGRP_AFF_WEAK, or LGRP_AFF_NONE.
If the $idtype is P_PID, the affinity is retrieved for
one of the LWPs in the process or set for all the LWPsof the process with process ID (PID) $id. The affinity
is retrieved or set for the LWP of the current processwith LWP ID $id if $idtype is P_LWPID. If $id is P_MYID,
then the current LWP or process is specified. There are different levels of affinity that can bespecified by a thread for a particuliar lgroup. The lev-
els of affinity are the following from strongest to weakest:LGRP_AFF_STRONG strong affinity
LGRP_AFF_WEAK weak affinity
LGRP_AFF_NONE no affinity
Upon successful completion, lgrp_affinity_set() returns
1. Otherwise, it returns undef and set $! to indicate
the error.See lgrp_affinity_set(3LGRP) for more information.
lgrp_affinity_get($idtype, $id, $lgrp)
This function returns the affinity that the LWP has to a given lgroup.See lgrp_affinity_get(3LGRP) for more information.
lgrp_latency_cookie($cookie, $from, $to,
[$between=LGRP_LAT_CPU_TO_MEM])
This function takes a cookie representing a snapshot of the lgroup hierarchy and returns the latency valuebetween a hardware resource in the $from lgroup to a
hardware resource in the $to lgroup. If $from is the
same lgroup as $to, the latency value within that lgroup
is returned.SunOS 5.11 Last change: 30 Aug 2006 8
Perl Library Functions Lgrp(3PERL)
The optional $between argument should be set to
LGRP_LAT_CPU_TO_MEM to specify between which hardware
resources the latency should be measured. The only validvalue is LGRP_LAT_CPU_TO_MEM, which represents latency
from CPU to memory.Upon successful completion, lgrp_latency_cookie() return
1. Otherwise, it returns undef and set $! to indicate
the error. For LGRP API version 1, thelgrp_latency_cookie() is an alias for lgrp_latency.()
See lgrp_latency_cookie(3LGRP) for more information.
lgrp_latency($from, $to)
This function is similiar to the lgrp_latency_cookie()
function, but returns the latency between the given lgroups at the given instant in time. Since lgroups can be freed and reallocated, this function might not be able to provide a consistent answer across calls. Forthat reason, lgrp_latency_cookie() should be used in its
place.See lgrp_latency(3LGRP) for more information.
lgrp_resources($cookie, $lgrp, $type)
This function returns the list of lgroups directly con-
taining resources of the specified type. The resources are represented by a set of lgroups in which each lgroup directly contains CPU and/or memory resources. The type can be specified as:LGRP_RSRC_CPU CPU resources
LGRP_RSRC_MEM memory resources
In the event of error, undef or an empty list isreturned and $! is set to indicate the error.
This function is available only for API version 2 and returns undef or an empty list for API version 1 andsets $! to EINVAL.
See lgrp_resources(3LGRP) for more information.
SunOS 5.11 Last change: 30 Aug 2006 9
Perl Library Functions Lgrp(3PERL)
lgrp_lgrps($cookie, [$lgrp])
This function returns a list of all lgroups in a hierar-
chy starting from $lgrp. If $lgrp is not specified, uses
the value of lgrp_root($cookie). This function returns
the empty list on failure. When called in scalar context, this function returns the total number of lgroups in the system.lgrp_leaves($cookie, [$lgrp])
This function returns a list of all leaf lgroups in ahierarchy starting from $lgrp. If $lgrp is not speci-
fied, this function uses the value oflgrp_root($cookie). It returns undef or an empty list on
failure. When called in scalar context, this function returns the total number of leaf lgroups in the system.lgrp_isleaf($cookie, $lgrp)
This function returns True if $lgrp is a leaf (has no
children). Otherwise it returns False. Object methodsnew([$view])
This method creates a new Sun::Solaris::Lgrp object. An
optional argument is passed to the lgrp_init() function.
By default this method uses LGRP_VIEW_OS.
cookie() This method returns a transparent cookie that can be passed to functions accepting the cookie.version([$version])
Without the argument, this method returns the current version of the liblgrp(3LIB) library. This method is awrapper for lgrp_version() with LGRP_VER_NONE as the
default version argument.SunOS 5.11 Last change: 30 Aug 2006 10
Perl Library Functions Lgrp(3PERL)
stale() This method returns T if the lgroup information in the object is stale and F otherwise. It is a wrapper forlgrp_cookie_stale().
view() This method returns the snapshot's view of the lgrouphierarchy. It is a wrapper for lgrp_view().
root() This method returns the root lgroup. It is a wrapper forlgrp_root().
children($lgrp)
This method returns the list of lgroups that are chil-
dren of the specified lgroup. It is a wrapper forlgrp_children().
parents($lgrp)
This method returns the list of lgroups that are parents of the specified lgroup. It is a wrapper forlgrp_parents().
nlgrps()This method returns the number of lgroups in the hierar-
chy. It is a wrapper for lgrp_nlgrps().
mem_size($lgrp, $type, $content)
This method returns the memory size of the given lgroupin bytes. It is a wrapper for lgrp_mem_size().
cpus($lgrp, $context)
This method returns the list of CPUs in the lgroupspecified by $lgrp. It is a wrapper for lgrp_cpus().
SunOS 5.11 Last change: 30 Aug 2006 11
Perl Library Functions Lgrp(3PERL)
resources($lgrp, $type)
This method returns the list of lgroups directly con-
taining resources of the specified type. It is a wrapperfor lgrp_resources().
home($idtype, $id)
This method returns the home lgroup for the given pro-
cess or thread. It is a wrapper for lgrp_home().
affinity_get($idtype, $id, $lgrp)
This method returns the affinity that the LWP has to agiven lgrp. It is a wrapper for lgrp_affinity_get().
affinity_set($idtype, $id, $lgrp, $affinity)
This method sets the affinity that the LWP or set ofLWPs specified by $idtype and $id have for the given
lgroup. It is a wrapper for lgrp_affinity_set.
lgrps([$lgrp])
This method returns list of all lgroups in a hierarchystarting from $lgrp or the lgrp_root() if $lgrp is not
specified. It is a wrapper for lgrp_lgrps().
leaves([$lgrp])
This method returns a list of all leaf lgroups in ahierarchy starting from $lgrp. If $lgrp is not speci-
fied, this method uses the value of lgrp_root(). It is a
wrapper for lgrp_leaves().
isleaf($lgrp)
This method returns True if $lgrp is leaf (has no chil-
dren) and False otherwise. It is a wrapper forlgrp_isleaf().
latency($from, $to)
This method returns the latency value between a hardwareresource in the $from lgroup to a hardware resource in
SunOS 5.11 Last change: 30 Aug 2006 12
Perl Library Functions Lgrp(3PERL)
the $to lgroup. It uses lgrp_latency() for version 1 of
liblgrp and lgrp_latency_cookie() for newer versions.
ExportsBy default nothing is exported from this module. The follow-
ing tags can be used to selectively import constants and functions defined in this module::LGRP_CONSTANTS LGRP_AFF_NONE, LGRP_AFF_STRONG,
LGRP_AFF_WEAK, LGRP_CONTENT_DIRECT,
LGRP_CONTENT_HIERARCHY, LGRP_MEM_SZ_FREE,
LGRP_MEM_SZ_INSTALLED, LGRP_VER_CURRENT,
LGRP_VER_NONE, LGRP_VIEW_CALLER,
LGRP_VIEW_OS, LGRP_NONE, LGRP_RSRC_CPU,
LGRP_RSRC_MEM, LGRP_CONTENT_ALL,
LGRP_LAT_CPU_TO_MEM
:PROC_CONSTANTS P_PID, P_LWPID, P_MYID
:CONSTANTS :LGRP_CONSTANTS, :PROC_CONSTANTS
:FUNCTIONS lgrp_affinity_get(), lgrp_affinity_set(),
lgrp_children(), lgrp_cookie_stale(),
lgrp_cpus(), lgrp_fini(), lgrp_home(),
lgrp_init(), lgrp_latency(),
lgrp_latency_cookie(), lgrp_mem_size(),
lgrp_nlgrps(), lgrp_parents(),
lgrp_root(), lgrp_version(), lgrp_view(),
lgrp_resources(), lgrp_lgrps(),
lgrp_leaves(), lgrp_isleaf()
:ALL :CONSTANTS, :FUNCTIONS Error values The functions in this module return undef or an empty listwhen an underlying library function fails. The $! is set to
provide more information values for the error. The following error codes are possible: EINVAL The value supplied is not valid. ENOMEM There was not enough system memory to complete an operation.SunOS 5.11 Last change: 30 Aug 2006 13
Perl Library Functions Lgrp(3PERL)
EPERM The effective user of the calling process does not have appropriate privileges, and its real or effective user ID does not match the real or effective user ID of one of the threads. ESRCH The specified process or thread was not found. Difference in the API versions The liblgrp(3LIB) library is versioned. The exact version that was used to compile a module is available through thelgrp_version() function.
Version 2 of the lgrp_user API introduced the following con-
stants and functions not present in version 1:LGRP_RSRC_CPU constant
LGRP_RSRC_MEM constant
LGRP_CONTENT_ALL constant
LGRP_LAT_CPU_TO_MEM constant
lgrp_resources() function
lgrp_latency_cookie() function
The LGRP_RSRC_CPU and LGRP_RSRC_MEM constants are not
defined for version 1. The lgrp_resources() function is
defined for version 1 but always returns an empty list. Thelgrp_latency_cookie() function is an alias for
lgrp_latency() for version 1.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWpl5u ||_____________________________|_____________________________|
| Interface Stability | Uncommitted ||_____________________________|_____________________________|
SEE ALSO
lgrp_affinity_get(3LGRP), lgrp_affinity_set(3LGRP),
lgrp_children(3LGRP), lgrp_cookie_stale(3LGRP),
lgrp_cpus(3LGRP), lgrp_fini(3LGRP), lgrp_home(3LGRP),
lgrp_init(3LGRP), lgrp_latency(3LGRP),
lgrp_latency_cookie(3LGRP), lgrp_mem_size(3LGRP),
SunOS 5.11 Last change: 30 Aug 2006 14
Perl Library Functions Lgrp(3PERL)
lgrp_nlgrps(3LGRP), lgrp_parents(3LGRP),
lgrp_resources(3LGRP), lgrp_root(3LGRP),
lgrp_version(3LGRP), lgrp_view(3LGRP), liblgrp(3LIB), attri-
butes(5)SunOS 5.11 Last change: 30 Aug 2006 15