Solaris::Lgrp - Perl interface to Solaris liblgrp(3LIB) library.
All functions return undef or empty list on failure. The $! variable contains the system errno value.
use Solaris::Lgrp qw(:ALL); # initialize lgroup interface my $cookie = lgrp_init(LGRP_VIEW_OS | LGRP_VIEW_CALLER); my $l = 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);
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.
liblgrp(3LIB)
sys/lgrp_sys.h
Functions returning scalar value indicate error by returning undef. The caller may examine the $! variable to get the errno value.
errno
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.
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_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.
P_PID, P_LWPID P_MYID
:LGRP_CONSTANTS, :PROC_CONSTANTS
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().
:CONSTANTS, :FUNCTIONS
new(), cookie(), stale(), view(), root(), children(), parents(), nlgrps(), mem_size(), cpus(), isleaf(), resources(), version(), home(), affinity_get(), affinity_set(), lgrps(), leaves(), latency().
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
LGRP_RSRC_MEM
LGRP_CONTENT_ALL
LGRP_LAT_CPU_TO_MEM
lgrp_resources()
lgrp_latency_cookie()
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.
The constants are exported with :CONSTANTS or :ALL tags:
use LGRP::User ':ALL'; or use LGRP::User ':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 API greater than 1.
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:
The value supplied is not valid.
There was not enough system memory to complete an operation.
The specified process or thread was not found.
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.
The 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.
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.
LGRP_VIEW_OS
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.
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.
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.
LGRP_VIEW_CALLER
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.
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.
P_PID
P_LWPID
P_MYID
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.
lgrp_home()
See lgrp_home(3LGRP) for more information.
Upon successful completion, the function returns whether the cookie is stale. Otherwise, it returns undef and sets $! errno to indicate the error.
The lgrp_cookie_stale() function will fail with EINVAL if the cookie is not valid.
EINVAL
See lgrp_cookie_stale(3LGRP) for more information.
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:
Everything within this hierarchy.
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.
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.
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.
See lgrp_parents(3LGRP) for more information.
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.
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.
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:
Free memory.
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:
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.
The function takes an interface version number, 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.
LGRP_VER_CURRENT
LGRP_VER_NONE
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. The application should be recompiled and might require further changes.
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.
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.
LGRP_AFF_STRONG
LGRP_AFF_WEAK
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:
Strong affinity.
Weak affinity.
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.
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.
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.
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.
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
CPU resources
Memory resources
This function is only available for API version2 and will return undef or empty list for API version 1 and set $! to EINVAL.
See lgrp_resources(3LGRP) for more information.
lgrp_resources(3LGRP)
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.
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.
Returns True if $lgrp is leaf (has no children), False otherwise.
Creates a new Solaris::Lgrp object. An optional argument is passed to lgrp_init() function. By default uses LGRP_VIEW_OS.
Returns a transparent cookie that may be passed to functions accepting cookie.
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.
Returns T if the lgroup information in the object is stale, F otherwise. It is a wrapper for lgrp_cookie_stale().
Returns the snapshot's view of the lgroup hierarchy. It is a wrapper for lgrp_view().
Returns the root lgroup. It is a wrapper for lgrp_root().
Returns the list of lgroups that are children of the specified lgroup. This is a wrapper for lgrp_children().
Returns the list of lgroups that are parents of the specified lgroup. This is a wrapper for lgrp_parents().
Returns the number of lgroups in the hierarchy. This is a wrapper for lgrp_nlgrps().
Returns the memory size of the given lgroup in bytes. This is a wrapper for lgrp_mem_size().
Returns the list of CPUs in the lgroup specified by $lgrp. This is a wrapper for lgrp_cpus().
Returns the list of lgroups directly containing resources of the specified type. This is a wrapper for lgrp_resources().
Returns the home lgroup for the given process or thread. This is a wrapper for lgrp_home().
Returns the affinity that the LWP has to a given lgrp. This is a wrapper for lgrp_affinity_get().
Sets of LWPs specified by the $idtype and $id arguments have for the given lgroup. This is a wrapper for lgrp_affinity_set().
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().
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().
Returns True if $lgrp is leaf (has no children), False otherwise. This is a wrapper for lgrp_isleaf().
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.
See attributes(5) for descriptions of the following attributes:
___________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | CPAN (http://www.cpan.org) | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________|
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(5)
To install Solaris::Lgrp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Solaris::Lgrp
CPAN shell
perl -MCPAN -e shell install Solaris::Lgrp
For more information on module installation, please visit the detailed CPAN module installation guide.