Sun::Solaris::Lgrp - Perl interface to Solaris liblgrp library.
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); 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);
User Contributed Perl Documentation pod::Lgrp(3)
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);
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 in "sys/lgrp_sys.h" header
file. It provides both the procedural and object interface to the
library. The procedural interface requires (in most cases) passing a
transparent cookie around. The object interface hides all the cookie
manipulations from the user.
Functions returning scalar value indicate error by returning undef. The
caller may examine the $! variable to get the "errno" value.
Functions returning list value return the number of elements in the
list when called in scalar context. In case of error the empty list is
return in the array context and undef is returned in the scalar
context.
CONSTANTS
The constants are exported with :CONSTANTS or :ALL tags:
use Sun::Solaris::Lgrp ':ALL';
or
use Sun::Solaris::Lgrp ':CONSTANTS';
The following constants are available for use in Perl programs:
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_INSTALLED
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 this module is
intended to provide a Perl interface to the routines in liblgrp(3LIB),
a very short description is given for the corresponding functions in
this module and a reference is given to the complete description in the
liblgrp(3LIB) man pages. Any differences or additional functionality in
the Perl module are highlighted and fully documented here.
lgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS])
The 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 representing this snapshot of the
lgroup hierarchy. This cookie should be used with other routines in
the lgroup interface needing the lgroup hierarchy. The lgrp_fini()
function should be called with the cookie when it is no longer
needed. Unlike lgrp_init (3LGRP), "LGRP_VIEW_OS" is assumed as the
default if no view is provided.
Upon successful completion, lgrp_init() returns a cookie. Otherwise
it returns undef and sets $! to indicate the error.
See lgrp_init(3LGRP) for more information.
lgrp_fini($cookie)
The function takes a cookie, frees the snapshot of the lgroup
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)
The 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 contains 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 by the given cookie.
Otherwise, undef is returned and $! is set.
See lgrp_view(3LGRP) for more information.
lgrp_home($idtype, $id)
Returns the home lgroup for the given process 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 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, the function returns whether the cookie
is stale. Otherwise, it returns undef and 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)
The function takes a cookie representing a snapshot of the lgroup
hierarchy and returns the list of CPUs in the lgroup specified by
$lgrp. The $context argument should be set to one of the following
values to specify whether the direct contents or everything in this
lgroup including its children should be returned:
LGRP_CONTENT_HIERARCHY
Everything within this hierarchy.
LGRP_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 case of error undef is returned in scalar context and $! is set
to indicate the error. In list context the empty list is returned
and $! is set.
See lgrp_cpus(3LGRP) for more information.
lgrp_children($cookie, $lgrp)
The 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() function returns the
number of children lgroups for the specified lgroup.
In case of error undef or empty list is returned and $! is set to
indicate the error.
See lgrp_children(3LGRP) for more information.
lgrp_parents($cookie, $lgrp)
The function takes a cookie representing a snapshot of the lgroup
hierarchy and returns the list of parent of the specified lgroup.
When called in scalar context, lgrp_parents() function returns the
number of parent lgroups for the specified lgroup.
In case of error undef or empty list is returned and $! is set to
indicate the error.
See lgrp_parents(3LGRP) for more information.
lgrp_nlgrps($cookie)
The 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 case of error undef is returned and $! is set to EINVAL
indicatng that the cookie is not valid.
See lgrp_nlgrps(3LGRP) for more information.
lgrp_root($cookie)
The function returns the root lgroup ID. In case 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)
The function takes a cookie representing a snapshot of the lgroup
hierarchy. The function returns the memory size of the given lgroup
in bytes. The $type argument should be set to one of the following
values:
LGRP_MEM_SZ_FREE
Free memory.
LGRP_MEM_SZ_INSTALLED
Installed memory.
The $content argument should be set to one of the following values
to specify whether the direct contents or everything in this lgroup
including its children should be returned:
LGRP_CONTENT_HIERARCHY
Everything within this hierarchy.
LGRP_CONTENT_DIRECT
Directly contained in 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 is returned.
Otherwise, undef is returned and $! is set to indicate the error.
See lgrp_mem_size(3LGRP) for more information.
lgrp_version([$version])
The function takes an interface version number, B$version>, as an
argument and returns an lgroup interface version. 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.
lgrp_affinity_set($idtype, $id, $lgrp, $affinity)
The function sets of LWPs specified by the $idtype and $id
arguments have for the given lgroup.
The function sets the affinity that the LWP or set of LWPs
specified by $idtype and $id have for the given lgroup. The lgroup
affinity can be set to "LGRP_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 LWPs of the process with
process id (PID) $id. The affinity is retrieved or set for the LWP
of the current process with 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 be specified by a
thread for a particuliar lgroup. The levels 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() return 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)
The function returns the affinity that the LWP has to a given lgrp.
See lgrp_affinity_get() for detailed description.
See lgrp_affinity_get(3LGRP) for more information.
lgrp_latency_cookie($cookie, $from, $to,
[$between=LGRP_LAT_CPU_TO_MEM])
The function takes a cookie representing a snapshot of the lgroup
hierarchy and returns the latency value between 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.
The optional between argument should be set to
"LGRP_LAT_CPU_TO_MEM" to specify between which hardware resources
the latency should be measured. Currently the only valid value 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 the lgrp_latency_cookie() is an alias for
lgrp_latency().
See lgrp_latency_cookie(3LGRP) for more information.
lgrp_latency($from, $to)
The 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 may be freed and reallocated, this function
may not be able to provide a consistent answer across calls. For
that reason, it is recommended that lgrp_latency_cookie() function
be used in its place.
See lgrp_latency(3LGRP) for more information.
lgrp_resources($cookie, $lgrp, $type)
Return the list of lgroups directly containing 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 case of error undef or empty list is returned and $! is set to
indicate the error.
This function is only available for API version 2 and will return
undef or empty list for API version 1 and set $! to "EINVAL".
See "lgrp_resources(3LGRP)" for more information.
lgrp_lgrps($cookie, [$lgrp])
Returns list of all lgroups in a hierarchy starting from $lgrp. If
$lgrp is not specified, uses the value of lgrp_root($cookie).
Returns the empty list on failure.
When called in scalar context, returns the total number of lgroups
in the system.
lgrp_leaves($cookie, [$lgrp])
Returns list of all leaf lgroups in a hierarchy starting from
$lgrp. If $lgrp is not specified, uses the value of
lgrp_root($cookie). Returns undef or empty list on failure.
When called in scalar context, returns the total number of leaf
lgroups in the system.
lgrp_isleaf($cookie, $lgrp)
Returns True if $lgrp is leaf (has no children), False otherwise.
Object Methods
new([$view])
Creates a new Sun::Solaris::Lgrp object. An optional argument is
passed to lgrp_init() function. By default uses "LGRP_VIEW_OS".
cookie()
Returns a transparent cookie that may be passed to functions
accepting cookie.
version([$version])
Without the argument returns the current version of the
liblgrp(3LIB) library. This is a wrapper for lgrp_version() with
"LGRP_VER_NONE" as the default version argument.
stale()
Returns T if the lgroup information in the object is stale, F
otherwise. It is a wrapper for lgrp_cookie_stale().
view()
Returns the snapshot's view of the lgroup hierarchy. It is a
wrapper for lgrp_view().
root()
Returns the root lgroup. It is a wrapper for lgrp_root().
children($lgrp)
Returns the list of lgroups that are children of the specified
lgroup. This is a wrapper for lgrp_children().
parents($lgrp)
Returns the list of lgroups that are parents of the specified
lgroup. This is a wrapper for lgrp_parents().
nlgrps()
Returns the number of lgroups in the hierarchy. This is a wrapper
for lgrp_nlgrps().
mem_size($lgrp, $type, $content)
Returns the memory size of the given lgroup in bytes. This is a
wrapper for lgrp_mem_size().
cpus($lgrp, $context)
Returns the list of CPUs in the lgroup specified by $lgrp. This is
a wrapper for lgrp_cpus().
resources($lgrp, $type)
Returns the list of lgroups directly containing resources of the
specified type. This is a wrapper for lgrp_resources().
home($idtype, $id)
Returns the home lgroup for the given process or thread. This is a
wrapper for lgrp_home().
affinity_get($idtype, $id, $lgrp)
Returns the affinity that the LWP has to a given lgrp. This is a
wrapper for lgrp_affinity_get().
affinity_set($idtype, $id, $lgrp, $affinity)
Sets of LWPs specified by the $idtype and $id arguments have for
the given lgroup. This is a wrapper for lgrp_affinity_set().
lgrps([$lgrp])
Returns list of all lgroups in a hierarchy starting from $lgrp (or
the lgrp_root() if $lgrp is not specified). This is a wrapper for
lgrp_lgrps().
leaves([$lgrp])
Returns list of all leaf lgroups in a hierarchy starting from
$lgrp. If $lgrp is not specified, uses the value of lgrp_root().
This is a wrapper for lgrp_leaves().
isleaf($lgrp)
Returns True if $lgrp is leaf (has no children), False otherwise.
This is a wrapper for lgrp_isleaf().
latency($from, $to)
Returns the latency value between a hardware resource in the $from
lgroup to a hardware resource in the $to lgroup. It will use
lgrp_latency() for version 1 of liblgrp(3LIB) and
lgrp_latency_cookie() for newer versions.
EXPORTS
By default nothing is exported from this module. The following 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(), lgrp_lgrps(), lgrp_leaves().
:ALL
:CONSTANTS, :FUNCTIONS
Error values
The functions in this module return undef or an empty list when 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.
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)" is versioned. The exact version which was used to
compile a module is available through lgrp_version function.
Version 2 of the lgrpp_user API introduced the following constants and
functions, nbot 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" are not defined for version 1.
The lgrp_resources() function is defined for version 1 but always
returns empty list. The lgrp_latency_cookie() function is an alias for
lgrp_latency for version 1.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
___________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWpl5u |
|_____________________________|_____________________________|
| Interface Stability | Unstable |
|_____________________________|_____________________________|
SEE ALSO
liblgrp(3LIB), 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_mem_size(3LGRP), lgrp_nlgrps(3LGRP),
lgrp_parents(3LGRP), lgrp_root(3LGRP), lgrp_version(3LGRP),
lgrp_view(3LGRP), lgrp_resources(3LGRP), lgrp_latency_cookie(3LGRP),
attributes(7)
perl v5.32.0 2022-06-28 pod::Lgrp(3)