1c6402783Sakolb# 2c6402783Sakolb# CDDL HEADER START 3c6402783Sakolb# 4c6402783Sakolb# The contents of this file are subject to the terms of the 5c6402783Sakolb# Common Development and Distribution License (the "License"). 6c6402783Sakolb# You may not use this file except in compliance with the License. 7c6402783Sakolb# 8c6402783Sakolb# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9c6402783Sakolb# or http://www.opensolaris.org/os/licensing. 10c6402783Sakolb# See the License for the specific language governing permissions 11c6402783Sakolb# and limitations under the License. 12c6402783Sakolb# 13c6402783Sakolb# When distributing Covered Code, include this CDDL HEADER in each 14c6402783Sakolb# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15c6402783Sakolb# If applicable, add the following below this CDDL HEADER, with the 16c6402783Sakolb# fields enclosed by brackets "[]" replaced with your own identifying 17c6402783Sakolb# information: Portions Copyright [yyyy] [name of copyright owner] 18c6402783Sakolb# 19c6402783Sakolb# CDDL HEADER END 20c6402783Sakolb# 21c6402783Sakolb 22c6402783Sakolb# 23c6402783Sakolb# Copyright 2006 Sun Microsystems, Inc. All rights reserved. 24c6402783Sakolb# Use is subject to license terms. 25c6402783Sakolb# 26c6402783Sakolb 27c6402783Sakolb# 28c6402783Sakolb# Sun::Solaris::Lgrp documentation. 29c6402783Sakolb# 30c6402783Sakolb 31c6402783Sakolb=head1 NAME 32c6402783Sakolb 33c6402783SakolbLgrp - Perl interface to Solaris liblgrp library. 34c6402783Sakolb 35c6402783Sakolb=head1 SYNOPSIS 36c6402783Sakolb 37c6402783Sakolb use Sun::Solaris::Lgrp qw(:ALL); 38c6402783Sakolb 39c6402783Sakolb # initialize lgroup interface 40c6402783Sakolb my $cookie = lgrp_init(LGRP_VIEW_OS | LGRP_VIEW_CALLER); 41c6402783Sakolb my $l = Sun::Solaris::Lgrp->new(LGRP_VIEW_OS | LGRP_VIEW_CALLER); 42c6402783Sakolb 43c6402783Sakolb my $version = lgrp_version(LGRP_VER_CURRENT | LGRP_VER_NONE); 44c6402783Sakolb $version = $l->version(LGRP_VER_CURRENT | LGRP_VER_NONE); 45c6402783Sakolb 46c6402783Sakolb $home = lgrp_home(P_PID, P_MYID); 47c6402783Sakolb $home = l->home(P_PID, P_MYID); 48c6402783Sakolb 49c6402783Sakolb lgrp_affinity_set(P_PID, $pid, $lgrp, 50c6402783Sakolb LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE); 51c6402783Sakolb $l->affinity_set(P_PID, $pid, $lgrp, 52c6402783Sakolb LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE); 53c6402783Sakolb 54c6402783Sakolb my $affinity = lgrp_affinity_get(P_PID, $pid, $lgrp); 55c6402783Sakolb $affinity = $l->affinity_get(P_PID, $pid, $lgrp); 56c6402783Sakolb 57c6402783Sakolb my $nlgrps = lgrp_nlgrps($cookie); 58c6402783Sakolb $nlgrps = $l->nlgrps(); 59c6402783Sakolb 60c6402783Sakolb my $root = lgrp_root($cookie); 61c6402783Sakolb $root = l->root(); 62c6402783Sakolb 63c6402783Sakolb $latency = lgrp_latency($lgrp1, $lgrp2); 64c6402783Sakolb $latency = $l->latency($lgrp1, $lgrp2); 65c6402783Sakolb 66c6402783Sakolb my @children = lgrp_children($cookie, $lgrp); 67c6402783Sakolb @children = l->children($lgrp); 68c6402783Sakolb 69c6402783Sakolb my @parents = lgrp_parents($cookie, $lgrp); 70c6402783Sakolb @parents = l->parents($lgrp); 71c6402783Sakolb 72c6402783Sakolb my @lgrps = lgrp_lgrps($cookie); 73c6402783Sakolb @lgrps = l->lgrps(); 74c6402783Sakolb 75c6402783Sakolb @lgrps = lgrp_lgrps($cookie, $lgrp); 76c6402783Sakolb @lgrps = l->lgrps($lgrp); 77c6402783Sakolb 78c6402783Sakolb my @leaves = lgrp_leaves($cookie); 79c6402783Sakolb @leaves = l->leaves(); 80c6402783Sakolb 81c6402783Sakolb my $is_leaf = lgrp_isleaf($cookie, $lgrp); 82c6402783Sakolb $is_leaf = $l->is_leaf($lgrp); 83c6402783Sakolb 84c6402783Sakolb my @cpus = lgrp_cpus($cookie, $lgrp, 85c6402783Sakolb LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 86c6402783Sakolb @cpus = l->cpus($lgrp, LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 87c6402783Sakolb 88c6402783Sakolb my $memsize = lgrp_mem_size($cookie, $lgrp, 89c6402783Sakolb LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE, 90c6402783Sakolb LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 91c6402783Sakolb $memsize = l->mem_size($lgrp, 92c6402783Sakolb LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE, 93c6402783Sakolb LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 94c6402783Sakolb 95c6402783Sakolb my $is_stale = lgrp_cookie_stale($cookie); 96c6402783Sakolb $stale = l->stale(); 97c6402783Sakolb 98c6402783Sakolb lgrp_fini($cookie); 99c6402783Sakolb 100c6402783Sakolb # The following is available for API version greater than 1: 101c6402783Sakolb 102c6402783Sakolb my @lgrps = lgrp_resources($cookie, $lgrp, LGRP_RSRC_CPU); 103c6402783Sakolb 104c6402783Sakolb # Get latencies from cookie 105c6402783Sakolb $latency = lgrp_latency_cookie($cookie, $from, $to); 106c6402783Sakolb 107c6402783Sakolb=head1 DESCRIPTION 108c6402783Sakolb 109c6402783SakolbThis module provides access to the C<liblgrp(3LIB)> library and to various 110c6402783Sakolbconstants and functions defined in C<sys/lgrp_sys.h> header file. It provides 111c6402783Sakolbboth the procedural and object interface to the library. The procedural 112c6402783Sakolbinterface requires (in most cases) passing a transparent cookie around. The 113c6402783Sakolbobject interface hides all the cookie manipulations from the user. 114c6402783Sakolb 115c6402783SakolbFunctions returning scalar value indicate error by returning B<undef>. The 116c6402783Sakolbcaller may examine the B<$!> variable to get the C<errno> value. 117c6402783Sakolb 118c6402783SakolbFunctions returning list value return the number of elements in the list when 119c6402783Sakolbcalled in scalar context. In case of error the empty list is return in the array 120c6402783Sakolbcontext and B<undef> is returned in the scalar context. 121c6402783Sakolb 122c6402783Sakolb=head2 CONSTANTS 123c6402783Sakolb 124c6402783SakolbThe constants are exported with B<:CONSTANTS> or B<:ALL> tags: 125c6402783Sakolb 126c6402783Sakolb use Sun::Solaris::Lgrp ':ALL'; 127c6402783Sakolb 128c6402783Sakolbor 129c6402783Sakolb 130c6402783Sakolb use Sun::Solaris::Lgrp ':CONSTANTS'; 131c6402783Sakolb 132c6402783SakolbThe following constants are available for use in Perl programs: 133c6402783Sakolb 134c6402783Sakolb 135c6402783Sakolb LGRP_NONE 136c6402783Sakolb 137c6402783Sakolb LGRP_VER_CURRENT 138c6402783Sakolb LGRP_VER_NONE 139c6402783Sakolb 140c6402783Sakolb LGRP_VIEW_CALLER 141c6402783Sakolb LGRP_VIEW_OS 142c6402783Sakolb 143c6402783Sakolb LGRP_AFF_NONE 144c6402783Sakolb LGRP_AFF_STRONG 145c6402783Sakolb LGRP_AFF_WEAK 146c6402783Sakolb 147c6402783Sakolb LGRP_CONTENT_DIRECT 148c6402783Sakolb LGRP_CONTENT_HIERARCHY 149c6402783Sakolb 150c6402783Sakolb LGRP_MEM_SZ_FREE 151c6402783Sakolb LGRP_MEM_SZ_INSTALLED 152c6402783Sakolb 153c6402783Sakolb LGRP_RSRC_CPU (1) 154c6402783Sakolb LGRP_RSRC_MEM (1) 155c6402783Sakolb LGRP_CONTENT_ALL (1) 156c6402783Sakolb LGRP_LAT_CPU_TO_MEM(1) 157c6402783Sakolb 158c6402783Sakolb P_PID 159c6402783Sakolb P_LWPID 160c6402783Sakolb P_MYID 161c6402783Sakolb 162c6402783Sakolb(1) Available for versions of the liblgrp(3LIB) API greater than 1. 163c6402783Sakolb 164c6402783Sakolb=head2 functions 165c6402783Sakolb 166c6402783SakolbA detailed description of each function follows. Since this module is intended 167c6402783Sakolbto provide a Perl interface to the routines in L<liblgrp(3LIB)>, a very short 168c6402783Sakolbdescription is given for the corresponding functions in this module and a 169c6402783Sakolbreference is given to the complete description in the L<liblgrp(3LIB)> man 170c6402783Sakolbpages. Any differences or additional functionality in the Perl module are 171c6402783Sakolbhighlighted and fully documented here. 172c6402783Sakolb 173c6402783Sakolb=over 174c6402783Sakolb 175c6402783Sakolb=item lgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS]) 176c6402783Sakolb 177c6402783SakolbThe function initializes the lgroup interface and takes a snapshot of the lgroup 178c6402783Sakolbhierarchy with the given view. Given the view, L<lgrp_init()> returns a cookie 179c6402783Sakolbrepresenting this snapshot of the lgroup hierarchy. This cookie should be used 180c6402783Sakolbwith other routines in the lgroup interface needing the lgroup hierarchy. The 181c6402783SakolbL<lgrp_fini()> function should be called with the cookie when it is no longer 182c6402783Sakolbneeded. Unlike L<lgrp_init (3LGRP)>, C<LGRP_VIEW_OS> is assumed as the default if 183c6402783Sakolbno view is provided. 184c6402783Sakolb 185c6402783SakolbUpon successful completion, L<lgrp_init()> returns a cookie. Otherwise it returns 186c6402783SakolbB<undef> and sets B<$!> to indicate the error. 187c6402783Sakolb 188c6402783SakolbSee L<lgrp_init(3LGRP)> for more information. 189c6402783Sakolb 190c6402783Sakolb=item lgrp_fini($cookie) 191c6402783Sakolb 192c6402783SakolbThe function takes a cookie, frees the snapshot of the lgroup hierarchy created 193c6402783Sakolbby L<lgrp_init()>, and cleans up anything else set up by L<lgrp_init()>. After 194c6402783Sakolbthis function is called, the cookie returned by the lgroup interface might no 195c6402783Sakolblonger be valid and should not be used. 196c6402783Sakolb 197c6402783SakolbUpon successful completion, 1 is returned. Otherwise, B<undef> is returned and 198c6402783SakolbB<$!> is set to indicate the error. 199c6402783Sakolb 200c6402783SakolbSee L<lgrp_fini(3LGRP)> for more information. 201c6402783Sakolb 202c6402783Sakolb=item lgrp_view($cookie) 203c6402783Sakolb 204c6402783SakolbThe function takes a cookie representing the snapshot of the lgroup hierarchy 205c6402783Sakolband returns the snapshot's view of the lgroup hierarchy. 206c6402783Sakolb 207c6402783SakolbIf the given view is C<LGRP_VIEW_CALLER>, the snapshot contains only the 208c6402783Sakolbresources that are available to the caller (such as those with respect to 209c6402783Sakolbprocessor sets). When the view is C<LGRP_VIEW_OS>, the snapshot contains what 210c6402783Sakolbis available to the operating system. 211c6402783Sakolb 212c6402783SakolbUpon succesful completion, the function returns the view for the snapshot of the 213c6402783Sakolblgroup hierarchy represented by the given cookie. Otherwise, B<undef> is 214c6402783Sakolbreturned and C<$!> is set. 215c6402783Sakolb 216c6402783SakolbSee L<lgrp_view(3LGRP)> for more information. 217c6402783Sakolb 218c6402783Sakolb=item lgrp_home($idtype, $id) 219c6402783Sakolb 220c6402783SakolbReturns the home lgroup for the given process or thread. The B<$idtype> argument 221c6402783Sakolbshould be C<P_PID> to specify a process and the B<$id> argument should be its 222c6402783Sakolbprocess id. Otherwise, the B<$idtype> argument should be C<P_LWPID> to specify a 223c6402783Sakolbthread and the B<$id> argument should be its LWP id. The value C<P_MYID> can be 224c6402783Sakolbused for the id argument to specify the current process or thread. 225c6402783Sakolb 226c6402783SakolbUpon successful completion, C<lgrp_home()> returns the id of the home lgroup of 227c6402783Sakolbthe specified process or thread. Otherwise, B<undef> is returned and B<$!> is 228c6402783Sakolbset to indicate the error. 229c6402783Sakolb 230c6402783SakolbSee L<lgrp_home(3LGRP)> for more information. 231c6402783Sakolb 232c6402783Sakolb=item lgrp_cookie_stale($cookie) 233c6402783Sakolb 234c6402783SakolbUpon successful completion, the function returns whether the cookie is 235c6402783Sakolbstale. Otherwise, it returns B<undef> and sets B<$!> to indicate the error. 236c6402783Sakolb 237c6402783SakolbThe L<lgrp_cookie_stale()> function will fail with C<EINVAL> if the cookie is 238c6402783Sakolbnot valid. 239c6402783Sakolb 240c6402783SakolbSee L<lgrp_cookie_stale(3LGRP)> for more information. 241c6402783Sakolb 242c6402783Sakolb=item lgrp_cpus($cookie, $lgrp, $context) 243c6402783Sakolb 244c6402783SakolbThe function takes a cookie representing a snapshot of the lgroup hierarchy and 245c6402783Sakolbreturns the list of CPUs in the lgroup specified by B<$lgrp>. The B<$context> 246c6402783Sakolbargument should be set to one of the following values to specify whether the 247c6402783Sakolbdirect contents or everything in this lgroup including its children should be 248c6402783Sakolbreturned: 249c6402783Sakolb 250c6402783Sakolb=over 251c6402783Sakolb 252c6402783Sakolb=item LGRP_CONTENT_HIERARCHY 253c6402783Sakolb 254c6402783SakolbEverything within this hierarchy. 255c6402783Sakolb 256c6402783Sakolb=item LGRP_CONTENT_DIRECT 257c6402783Sakolb 258c6402783SakolbDirectly contained in lgroup. 259c6402783Sakolb 260c6402783Sakolb=back 261c6402783Sakolb 262c6402783SakolbWhen called in scalar context, L<lgrp_cpus()> function returns the number of 263c6402783SakolbCPUs, contained in the specified lgroup. 264c6402783Sakolb 265c6402783SakolbIn case of error B<undef> is returned in scalar context and B<$!> is set to 266c6402783Sakolbindicate the error. In list context the empty list is returned and B<$!> is set. 267c6402783Sakolb 268c6402783SakolbSee L<lgrp_cpus(3LGRP)> for more information. 269c6402783Sakolb 270c6402783Sakolb=item lgrp_children($cookie, $lgrp) 271c6402783Sakolb 272c6402783SakolbThe function takes a cookie representing a snapshot of the lgroup hierarchy and 273c6402783Sakolbreturns the list of lgroups that are children of the specified lgroup. 274c6402783Sakolb 275c6402783SakolbWhen called in scalar context, L<lgrp_children()> function returns the number of 276c6402783Sakolbchildren lgroups for the specified lgroup. 277c6402783Sakolb 278c6402783SakolbIn case of error B<undef> or empty list is returned and B<$!> is set to indicate 279c6402783Sakolbthe error. 280c6402783Sakolb 281c6402783SakolbSee L<lgrp_children(3LGRP)> for more information. 282c6402783Sakolb 283c6402783Sakolb=item lgrp_parents($cookie, $lgrp) 284c6402783Sakolb 285c6402783SakolbThe function takes a cookie representing a snapshot of the lgroup hierarchy and 286c6402783Sakolbreturns the list of parent of the specified lgroup. 287c6402783Sakolb 288c6402783SakolbWhen called in scalar context, L<lgrp_parents()> function returns the number of 289c6402783Sakolbparent lgroups for the specified lgroup. 290c6402783Sakolb 291c6402783SakolbIn case of error B<undef> or empty list is returned and B<$!> is set to indicate 292c6402783Sakolbthe error. 293c6402783Sakolb 294c6402783SakolbSee L<lgrp_parents(3LGRP)> for more information. 295c6402783Sakolb 296c6402783Sakolb=item lgrp_nlgrps($cookie) 297c6402783Sakolb 298c6402783SakolbThe function takes a cookie representing a snapshot of the lgroup hierarchy. It 299c6402783Sakolbreturns the number of lgroups in the hierarchy where the number is always at 300c6402783Sakolbleast one. 301c6402783Sakolb 302c6402783SakolbIn case of error B<undef> is returned and B<$!> is set to EINVAL indicatng that 303c6402783Sakolbthe cookie is not valid. 304c6402783Sakolb 305c6402783SakolbSee L<lgrp_nlgrps(3LGRP)> for more information. 306c6402783Sakolb 307c6402783Sakolb=item lgrp_root($cookie) 308c6402783Sakolb 309c6402783SakolbThe function returns the root lgroup ID. In case of error B<undef> is returned 310c6402783Sakolband B<$!> is set to EINVAL indicatng that the cookie is not valid. 311c6402783Sakolb 312c6402783SakolbSee L<lgrp_root(3LGRP)> for more information. 313c6402783Sakolb 314c6402783Sakolb=item lgrp_mem_size($cookie, $lgrp, $type, $content) 315c6402783Sakolb 316c6402783SakolbThe function takes a cookie representing a snapshot of the lgroup hierarchy. The 317c6402783Sakolbfunction returns the memory size of the given lgroup in bytes. The B<$type> 318c6402783Sakolbargument should be set to one of the following values: 319c6402783Sakolb 320c6402783Sakolb=over 321c6402783Sakolb 322c6402783Sakolb=item LGRP_MEM_SZ_FREE 323c6402783Sakolb 324c6402783SakolbFree memory. 325c6402783Sakolb 326c6402783Sakolb=item LGRP_MEM_SZ_INSTALLED 327c6402783Sakolb 328c6402783SakolbInstalled memory. 329c6402783Sakolb 330c6402783Sakolb=back 331c6402783Sakolb 332c6402783SakolbThe B<$content> argument should be set to one of the following values to specify 333c6402783Sakolbwhether the direct contents or everything in this lgroup including its children 334c6402783Sakolbshould be returned: 335c6402783Sakolb 336c6402783Sakolb=over 337c6402783Sakolb 338c6402783Sakolb=item LGRP_CONTENT_HIERARCHY 339c6402783Sakolb 340c6402783SakolbEverything within this hierarchy. 341c6402783Sakolb 342c6402783Sakolb=item LGRP_CONTENT_DIRECT 343c6402783Sakolb 344c6402783SakolbDirectly contained in lgroup. 345c6402783Sakolb 346c6402783Sakolb=back 347c6402783Sakolb 348c6402783SakolbThe total sizes include all the memory in the lgroup including its children, 349c6402783Sakolbwhile the others reflect only the memory contained directly in the given lgroup. 350c6402783Sakolb 351c6402783SakolbUpon successful completion, the size in bytes is returned. Otherwise, B<undef> 352c6402783Sakolbis returned and B<$!> is set to indicate the error. 353c6402783Sakolb 354c6402783SakolbSee L<lgrp_mem_size(3LGRP)> for more information. 355c6402783Sakolb 356c6402783Sakolb=item lgrp_version([$version]) 357c6402783Sakolb 358c6402783SakolbThe function takes an interface version number, B$version>, as an argument and 359c6402783Sakolbreturns an lgroup interface version. The B<$version> argument should be the 360c6402783Sakolbvalue of C<LGRP_VER_CURRENT> or C<LGRP_VER_NONE> to find out the current lgroup 361c6402783Sakolbinterface version on the running system. 362c6402783Sakolb 363c6402783SakolbIf B<$version> is still supported by the implementation, then L<lgrp_version()> 364c6402783Sakolbreturns the requested version. If C<LGRP_VER_NONE> is returned, the 365c6402783Sakolbimplementation cannot support the requested version. 366c6402783Sakolb 367c6402783SakolbIf B<$version> is C<LGRP_VER_NONE>, L<lgrp_version()> returns the current version of 368c6402783Sakolbthe library. 369c6402783Sakolb 370c6402783SakolbThe following example tests whether the version of the 371c6402783Sakolbinterface used by the caller is supported: 372c6402783Sakolb 373c6402783Sakolb lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or 374c6402783Sakolb die("Built with unsupported lgroup interface"); 375c6402783Sakolb 376c6402783SakolbSee L<lgrp_version(3LGRP)> for more information. 377c6402783Sakolb 378c6402783Sakolb=item lgrp_affinity_set($idtype, $id, $lgrp, $affinity) 379c6402783Sakolb 380c6402783SakolbThe function sets of LWPs specified by the B<$idtype> and B<$id> arguments have 381c6402783Sakolbfor the given lgroup. 382c6402783Sakolb 383c6402783SakolbThe function sets the affinity that the LWP or set of LWPs specified by $idtype 384c6402783Sakolband $id have for the given lgroup. The lgroup affinity can be set to 385c6402783SakolbC<LGRP_AFF_STRONG>, C<LGRP_AFF_WEAK>, or C<LGRP_AFF_NONE>. 386c6402783Sakolb 387c6402783SakolbIf the B<$idtype> is C<P_PID>, the affinity is retrieved for one of the LWPs in 388c6402783Sakolbthe process or set for all the LWPs of the process with process id (PID) B<$id>. 389c6402783SakolbThe affinity is retrieved or set for the LWP of the current process with LWP id 390c6402783Sakolb$id if idtype is C<P_LWPID>. If $id is C<P_MYID>, then the current LWP or 391c6402783Sakolbprocess is specified. 392c6402783Sakolb 393c6402783SakolbThere are different levels of affinity that can be specified by a thread for a 394c6402783Sakolbparticuliar lgroup. The levels of affinity are the following from strongest to 395c6402783Sakolbweakest: 396c6402783Sakolb 397c6402783Sakolb=over 398c6402783Sakolb 399c6402783Sakolb=item LGRP_AFF_STRONG 400c6402783Sakolb 401c6402783SakolbStrong affinity. 402c6402783Sakolb 403c6402783Sakolb=item LGRP_AFF_WEAK 404c6402783Sakolb 405c6402783SakolbWeak affinity. 406c6402783Sakolb 407c6402783Sakolb=item LGRP_AFF_NONE 408c6402783Sakolb 409c6402783SakolbNo affinity. 410c6402783Sakolb 411c6402783Sakolb=back 412c6402783Sakolb 413c6402783SakolbUpon successful completion, L<lgrp_affinity_set()> return 1. Otherwise, it 414c6402783Sakolbreturns B<undef> and set B<$!> to indicate the error. 415c6402783Sakolb 416c6402783SakolbSee L<lgrp_affinity_set(3LGRP)> for more information. 417c6402783Sakolb 418c6402783Sakolb=item lgrp_affinity_get($idtype, $id, $lgrp) 419c6402783Sakolb 420c6402783SakolbThe function returns the affinity that the LWP has to a given lgrp. See 421c6402783SakolbL<lgrp_affinity_get()> for detailed description. 422c6402783Sakolb 423c6402783SakolbSee L<lgrp_affinity_get(3LGRP)> for more information. 424c6402783Sakolb 425c6402783Sakolb=item lgrp_latency_cookie($cookie, $from, $to, [$between=LGRP_LAT_CPU_TO_MEM]) 426c6402783Sakolb 427c6402783SakolbThe function takes a cookie representing a snapshot of the lgroup hierarchy and 428c6402783Sakolbreturns the latency value between a hardware resource in the $from lgroup to a 429c6402783Sakolbhardware resource in the B<$to> lgroup. If B<$from> is the same lgroup as $to, the 430c6402783Sakolblatency value within that lgroup is returned. 431c6402783Sakolb 432c6402783SakolbThe optional B<between> argument should be set to C<LGRP_LAT_CPU_TO_MEM> to specify 433c6402783Sakolbbetween which hardware resources the latency should be measured. Currently the 434c6402783Sakolbonly valid value is C<LGRP_LAT_CPU_TO_MEM> which represents latency from CPU to 435c6402783Sakolbmemory. 436c6402783Sakolb 437c6402783SakolbUpon successful completion, lgrp_latency_cookie() return 1. Otherwise, it 438c6402783Sakolbreturns B<undef> and set B<$!> to indicate the error. For LGRP API version 1 the 439c6402783SakolbL<lgrp_latency_cookie()> is an alias for L<lgrp_latency()>. 440c6402783Sakolb 441c6402783SakolbSee L<lgrp_latency_cookie(3LGRP)> for more information. 442c6402783Sakolb 443c6402783Sakolb=item lgrp_latency($from, $to) 444c6402783Sakolb 445c6402783SakolbThe function is similiar to the L<lgrp_latency_cookie()> function, but returns the 446c6402783Sakolblatency between the given lgroups at the given instant in time. Since lgroups 447c6402783Sakolbmay be freed and reallocated, this function may not be able to provide a 448c6402783Sakolbconsistent answer across calls. For that reason, it is recommended that 449c6402783SakolbL<lgrp_latency_cookie()> function be used in its place. 450c6402783Sakolb 451c6402783SakolbSee L<lgrp_latency(3LGRP)> for more information. 452c6402783Sakolb 453c6402783Sakolb=item lgrp_resources($cookie, $lgrp, $type) 454c6402783Sakolb 455c6402783SakolbReturn the list of lgroups directly containing resources of the specified type. 456c6402783SakolbThe resources are represented by a set of lgroups in which each lgroup directly 457c6402783Sakolbcontains CPU and/or memory resources. 458c6402783Sakolb 459c6402783SakolbThe type can be specified as 460c6402783Sakolb 461c6402783Sakolb=over 462c6402783Sakolb 463c6402783Sakolb=item C<LGRP_RSRC_CPU> 464c6402783Sakolb 465c6402783SakolbCPU resources 466c6402783Sakolb 467c6402783Sakolb=item C<LGRP_RSRC_MEM> 468c6402783Sakolb 469c6402783SakolbMemory resources 470c6402783Sakolb 471c6402783Sakolb=back 472c6402783Sakolb 473c6402783SakolbIn case of error B<undef> or empty list is returned and B<$!> is set to indicate 474c6402783Sakolbthe error. 475c6402783Sakolb 476c6402783SakolbThis function is only available for API version 2 and will return B<undef> or 477c6402783Sakolbempty list for API version 1 and set $! to C<EINVAL>. 478c6402783Sakolb 479c6402783SakolbSee C<lgrp_resources(3LGRP)> for more information. 480c6402783Sakolb 481c6402783Sakolb=item lgrp_lgrps($cookie, [$lgrp]) 482c6402783Sakolb 483c6402783SakolbReturns list of all lgroups in a hierarchy starting from $lgrp. If B<$lgrp> is 484c6402783Sakolbnot specified, uses the value of lgrp_root($cookie). Returns the empty list on 485c6402783Sakolbfailure. 486c6402783Sakolb 487c6402783SakolbWhen called in scalar context, returns the total number of lgroups in the 488c6402783Sakolbsystem. 489c6402783Sakolb 490c6402783Sakolb=item lgrp_leaves($cookie, [$lgrp]) 491c6402783Sakolb 492c6402783SakolbReturns list of all leaf lgroups in a hierarchy starting from $lgrp. If $lgrp is 493c6402783Sakolbnot specified, uses the value of lgrp_root($cookie). Returns B<undef> or empty 494c6402783Sakolblist on failure. 495c6402783Sakolb 496c6402783SakolbWhen called in scalar context, returns the total number of leaf lgroups in the 497c6402783Sakolbsystem. 498c6402783Sakolb 499c6402783Sakolb=item lgrp_isleaf($cookie, $lgrp) 500c6402783Sakolb 501c6402783SakolbReturns B<True> if $lgrp is leaf (has no children), B<False> otherwise. 502c6402783Sakolb 503c6402783Sakolb=back 504c6402783Sakolb 505c6402783Sakolb=head2 Object Methods 506c6402783Sakolb 507c6402783Sakolb=over 508c6402783Sakolb 509c6402783Sakolb=item new([$view]) 510c6402783Sakolb 511c6402783SakolbCreates a new Sun::Solaris::Lgrp object. An optional argument is passed to 512c6402783SakolbL<lgrp_init()> function. By default uses C<LGRP_VIEW_OS>. 513c6402783Sakolb 514c6402783Sakolb=item cookie() 515c6402783Sakolb 516c6402783SakolbReturns a transparent cookie that may be passed to functions accepting cookie. 517c6402783Sakolb 518c6402783Sakolb=item version([$version]) 519c6402783Sakolb 520c6402783SakolbWithout the argument returns the current version of the L<liblgrp(3LIB)> 521c6402783Sakolblibrary. This is a wrapper for L<lgrp_version()> with C<LGRP_VER_NONE> as the 522c6402783Sakolbdefault version argument. 523c6402783Sakolb 524c6402783Sakolb=item stale() 525c6402783Sakolb 526c6402783SakolbReturns B<T> if the lgroup information in the object is stale, B<F> 527c6402783Sakolbotherwise. It is a wrapper for L<lgrp_cookie_stale()>. 528c6402783Sakolb 529c6402783Sakolb=item view() 530c6402783Sakolb 531c6402783SakolbReturns the snapshot's view of the lgroup hierarchy. It is a wrapper for 532c6402783SakolbL<lgrp_view()>. 533c6402783Sakolb 534c6402783Sakolb=item root() 535c6402783Sakolb 536c6402783SakolbReturns the root lgroup. It is a wrapper for L<lgrp_root()>. 537c6402783Sakolb 538c6402783Sakolb=item children($lgrp) 539c6402783Sakolb 540c6402783SakolbReturns the list of lgroups that are children of the specified lgroup. This is a 541c6402783Sakolbwrapper for L<lgrp_children()>. 542c6402783Sakolb 543c6402783Sakolb=item parents($lgrp) 544c6402783Sakolb 545c6402783SakolbReturns the list of lgroups that are parents of the specified lgroup. This is a 546c6402783Sakolbwrapper for L<lgrp_parents()>. 547c6402783Sakolb 548c6402783Sakolb=item nlgrps() 549c6402783Sakolb 550c6402783SakolbReturns the number of lgroups in the hierarchy. This is a wrapper for 551c6402783SakolbL<lgrp_nlgrps()>. 552c6402783Sakolb 553c6402783Sakolb=item mem_size($lgrp, $type, $content) 554c6402783Sakolb 555c6402783SakolbReturns the memory size of the given lgroup in bytes. This is a wrapper for 556c6402783SakolbL<lgrp_mem_size()>. 557c6402783Sakolb 558c6402783Sakolb=item cpus($lgrp, $context) 559c6402783Sakolb 560c6402783SakolbReturns the list of CPUs in the lgroup specified by $lgrp. This is a wrapper for 561c6402783SakolbL<lgrp_cpus()>. 562c6402783Sakolb 563c6402783Sakolb=item resources($lgrp, $type) 564c6402783Sakolb 565c6402783SakolbReturns the list of lgroups directly containing resources of the specified 566c6402783Sakolbtype. This is a wrapper for L<lgrp_resources()>. 567c6402783Sakolb 568c6402783Sakolb=item home($idtype, $id) 569c6402783Sakolb 570c6402783SakolbReturns the home lgroup for the given process or thread. This is a wrapper for 571c6402783SakolbL<lgrp_home()>. 572c6402783Sakolb 573c6402783Sakolb=item affinity_get($idtype, $id, $lgrp) 574c6402783Sakolb 575c6402783SakolbReturns the affinity that the LWP has to a given lgrp. This is a wrapper for 576c6402783SakolbL<lgrp_affinity_get()>. 577c6402783Sakolb 578c6402783Sakolb=item affinity_set($idtype, $id, $lgrp, $affinity) 579c6402783Sakolb 580c6402783SakolbSets of LWPs specified by the $idtype and $id arguments have for the given lgroup. 581c6402783SakolbThis is a wrapper for L<lgrp_affinity_set()>. 582c6402783Sakolb 583c6402783Sakolb=item lgrps([$lgrp]) 584c6402783Sakolb 585c6402783SakolbReturns list of all lgroups in a hierarchy starting from $lgrp (or the 586c6402783SakolbL<lgrp_root()> if $lgrp is not specified). This is a wrapper for L<lgrp_lgrps()>. 587c6402783Sakolb 588c6402783Sakolb=item leaves([$lgrp]) 589c6402783Sakolb 590c6402783SakolbReturns list of all leaf lgroups in a hierarchy starting from B<$lgrp>. If $lgrp 591c6402783Sakolbis not specified, uses the value of lgrp_root(). This is a wrapper for 592c6402783SakolbL<lgrp_leaves()>. 593c6402783Sakolb 594c6402783Sakolb=item isleaf($lgrp) 595c6402783Sakolb 596c6402783SakolbReturns B<True> if B<$lgrp> is leaf (has no children), B<False> otherwise. 597c6402783SakolbThis is a wrapper for L<lgrp_isleaf()>. 598c6402783Sakolb 599c6402783Sakolb=item latency($from, $to) 600c6402783Sakolb 601c6402783SakolbReturns the latency value between a hardware resource in the $from lgroup to a 602c6402783Sakolbhardware resource in the B<$to> lgroup. It will use L<lgrp_latency()> for 603c6402783Sakolbversion 1 of liblgrp(3LIB) and L<lgrp_latency_cookie()> for newer versions. 604c6402783Sakolb 605c6402783Sakolb=back 606c6402783Sakolb 607c6402783Sakolb=head2 EXPORTS 608c6402783Sakolb 609c6402783SakolbBy default nothing is exported from this module. The following tags can be used 610c6402783Sakolbto selectively import constants and functions defined in this module: 611c6402783Sakolb 612c6402783Sakolb=over 613c6402783Sakolb 614c6402783Sakolb=item :LGRP_CONSTANTS 615c6402783Sakolb 616c6402783SakolbLGRP_AFF_NONE, LGRP_AFF_STRONG, LGRP_AFF_WEAK, LGRP_CONTENT_DIRECT, 617c6402783SakolbLGRP_CONTENT_HIERARCHY, LGRP_MEM_SZ_FREE, LGRP_MEM_SZ_INSTALLED, 618c6402783SakolbLGRP_VER_CURRENT, LGRP_VER_NONE, LGRP_VIEW_CALLER, LGRP_VIEW_OS, 619c6402783SakolbLGRP_NONE, LGRP_RSRC_CPU, LGRP_RSRC_MEM, LGRP_CONTENT_ALL, 620c6402783SakolbLGRP_LAT_CPU_TO_MEM. 621c6402783Sakolb 622c6402783Sakolb=item :PROC_CONSTANTS 623c6402783Sakolb 624c6402783SakolbP_PID, P_LWPID P_MYID 625c6402783Sakolb 626c6402783Sakolb=item :CONSTANTS 627c6402783Sakolb 628c6402783Sakolb:LGRP_CONSTANTS, :PROC_CONSTANTS 629c6402783Sakolb 630c6402783Sakolb=item :FUNCTIONS 631c6402783Sakolb 632c6402783Sakolblgrp_affinity_get(), lgrp_affinity_set(), lgrp_children(), lgrp_cookie_stale(), 633c6402783Sakolblgrp_cpus(), lgrp_fini(), lgrp_home(), lgrp_init(), lgrp_latency(), 634c6402783Sakolblgrp_latency_cookie(), lgrp_mem_size(), lgrp_nlgrps(), lgrp_parents(), 635c6402783Sakolblgrp_root(), lgrp_version(), lgrp_view(), lgrp_resources(), 636c6402783Sakolblgrp_lgrps(), lgrp_leaves(), lgrp_isleaf(), lgrp_lgrps(), lgrp_leaves(). 637c6402783Sakolb 638c6402783Sakolb=item :ALL 639c6402783Sakolb 640c6402783Sakolb:CONSTANTS, :FUNCTIONS 641c6402783Sakolb 642c6402783Sakolb=back 643c6402783Sakolb 644c6402783Sakolb=head2 Error values 645c6402783Sakolb 646c6402783SakolbThe functions in this module return B<undef> or an empty list when an underlying 647c6402783Sakolblibrary function fails. The B<$!> is set to provide more information values for 648c6402783Sakolbthe error. The following error codes are possible: 649c6402783Sakolb 650c6402783Sakolb=over 651c6402783Sakolb 652c6402783Sakolb=item EINVAL 653c6402783Sakolb 654c6402783SakolbThe value supplied is not valid. 655c6402783Sakolb 656c6402783Sakolb=item ENOMEM 657c6402783Sakolb 658c6402783SakolbThere was not enough system memory to complete an operation. 659c6402783Sakolb 660c6402783Sakolb=item EPERM 661c6402783Sakolb 662c6402783SakolbThe effective user of the calling process does not have appropriate privileges, 663c6402783Sakolband its real or effective user ID does not match the real or effective user ID 664c6402783Sakolbof one of the threads. 665c6402783Sakolb 666c6402783Sakolb=item ESRCH 667c6402783Sakolb 668c6402783SakolbThe specified process or thread was not found. 669c6402783Sakolb 670c6402783Sakolb=back 671c6402783Sakolb 672c6402783Sakolb=head2 Difference in the API versions 673c6402783Sakolb 674c6402783SakolbThe C<liblgrp(3LIB)> is versioned. The exact version which was used to compile a 675c6402783Sakolbmodule is available through B<lgrp_version> function. 676c6402783Sakolb 677c6402783SakolbVersion 2 of the lgrpp_user API introduced the following constants and 678c6402783Sakolbfunctions, nbot present in version 1: 679c6402783Sakolb 680c6402783Sakolb=over 681c6402783Sakolb 682c6402783Sakolb=item C<LGRP_RSRC_CPU> constant 683c6402783Sakolb 684c6402783Sakolb=item C<LGRP_RSRC_MEM> constant 685c6402783Sakolb 686c6402783Sakolb=item C<LGRP_CONTENT_ALL> constant 687c6402783Sakolb 688c6402783Sakolb=item C<LGRP_LAT_CPU_TO_MEM> constant 689c6402783Sakolb 690c6402783Sakolb=item C<lgrp_resources()> function 691c6402783Sakolb 692c6402783Sakolb=item C<lgrp_latency_cookie()> function 693c6402783Sakolb 694c6402783Sakolb=back 695c6402783Sakolb 696c6402783SakolbThe C<LGRP_RSRC_CPU> and C<LGRP_RSRC_MEM> are not defined for version 1. The 697c6402783SakolbL<lgrp_resources()> function is defined for version 1 but always returns empty 698c6402783Sakolblist. The L<lgrp_latency_cookie()> function is an alias for lgrp_latency for 699c6402783Sakolbversion 1. 700c6402783Sakolb 701c6402783Sakolb=head1 ATTRIBUTES 702c6402783Sakolb 703*bbf21555SRichard LoweSee L<attributes(7)> for descriptions of the following attributes: 704c6402783Sakolb 705c6402783Sakolb ___________________________________________________________ 706c6402783Sakolb | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 707c6402783Sakolb |_____________________________|_____________________________| 708c6402783Sakolb | Availability | SUNWpl5u | 709c6402783Sakolb |_____________________________|_____________________________| 710c6402783Sakolb | Interface Stability | Unstable | 711c6402783Sakolb |_____________________________|_____________________________| 712c6402783Sakolb 713c6402783Sakolb 714c6402783Sakolb=head1 SEE ALSO 715c6402783Sakolb 716c6402783SakolbL<liblgrp(3LIB)>, 717c6402783SakolbL<lgrp_affinity_get(3LGRP)>, 718c6402783SakolbL<lgrp_affinity_set(3LGRP)>, 719c6402783SakolbL<lgrp_children(3LGRP)>, 720c6402783SakolbL<lgrp_cookie_stale(3LGRP)>, 721c6402783SakolbL<lgrp_cpus(3LGRP)>, 722c6402783SakolbL<lgrp_fini(3LGRP)>, 723c6402783SakolbL<lgrp_home(3LGRP)>, 724c6402783SakolbL<lgrp_init(3LGRP)>, 725c6402783SakolbL<lgrp_latency(3LGRP)>, 726c6402783SakolbL<lgrp_mem_size(3LGRP)>, 727c6402783SakolbL<lgrp_nlgrps(3LGRP)>, 728c6402783SakolbL<lgrp_parents(3LGRP)>, 729c6402783SakolbL<lgrp_root(3LGRP)>, 730c6402783SakolbL<lgrp_version(3LGRP)>, 731c6402783SakolbL<lgrp_view(3LGRP)>, 732c6402783SakolbL<lgrp_resources(3LGRP)>, 733c6402783SakolbL<lgrp_latency_cookie(3LGRP)>, 734*bbf21555SRichard LoweL<attributes(7)> 735c6402783Sakolb 736c6402783Sakolb=cut 737