1 '\" te 2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .TH LGRP 3PERL "April 9, 2016" 7 .SH NAME 8 Lgrp \- Perl interface to Solaris liblgrp library 9 .SH SYNOPSIS 10 .LP 11 .nf 12 use Sun::Solaris::Lgrp qw(:ALL); 13 14 # initialize lgroup interface 15 my $cookie = lgrp_init(LGRP_VIEW_OS | LGRP_VIEW_CALLER); 16 my $l = Sun::Solaris::Lgrp->new(LGRP_VIEW_OS | 17 LGRP_VIEW_CALLER); 18 19 my $version = lgrp_version(LGRP_VER_CURRENT | LGRP_VER_NONE); 20 $version = $l->version(LGRP_VER_CURRENT | LGRP_VER_NONE); 21 22 $home = lgrp_home(P_PID, P_MYID); 23 $home = l->home(P_PID, P_MYID); 24 25 lgrp_affinity_set(P_PID, $\fIpid\fR, $\fIlgrp\fR, 26 LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE); 27 $l->affinity_set(P_PID, $\fIpid\fR, $\fIlgrp\fR, 28 LGRP_AFF_STRONG | LGRP_AFF_WEAK | LGRP_AFF_NONE); 29 30 my $affinity = lgrp_affinity_get(P_PID, $\fIpid\fR, $\fIlgrp\fR); 31 $affinity = $l->affinity_get(P_PID, $\fIpid\fR, $\fIlgrp\fR); 32 33 my $nlgrps = lgrp_nlgrps($\fIcookie\fR); 34 $nlgrps = $l->nlgrps(); 35 36 my $root = lgrp_root($\fIcookie\fR); 37 $root = l->root(); 38 39 $latency = lgrp_latency($\fIlgrp1\fR, $\fIlgrp2\fR); 40 $latency = $l->latency($\fIlgrp1\fR, $\fIlgrp2\fR); 41 42 my @children = lgrp_children($\fIcookie\fR, $\fIlgrp\fR); 43 @children = l->children($lgrp); 44 45 my @parents = lgrp_parents($\fIcookie\fR, $\fIlgrp\fR); 46 @parents = l->parents($\fIlgrp\fR); 47 48 my @lgrps = lgrp_lgrps($\fIcookie\fR); 49 @lgrps = l->lgrps(); 50 51 @lgrps = lgrp_lgrps($\fIcookie\fR, $\fIlgrp\fR); 52 @lgrps = l->lgrps($\fIlgrp\fR); 53 54 my @leaves = lgrp_leaves($\fIcookie\fR); 55 @leaves = l->leaves(); 56 57 my $is_leaf = lgrp_isleaf($\fIcookie\fR, $\fIlgrp\fR); 58 $is_leaf = $l->is_leaf($\fIlgrp\fR); 59 60 my @cpus = lgrp_cpus($\fIcookie\fR, $\fIlgrp\fR, 61 LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 62 @cpus = l->cpus($\fIlgrp\fR, LGRP_CONTENT_HIERARCHY | 63 LGRP_CONTENT_DIRECT); 64 65 my $memsize = lgrp_mem_size($\fIcookie\fR, $\fIlgrp\fR, 66 LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE, 67 LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 68 $memsize = l->mem_size($\fIlgrp\fR, 69 LGRP_MEM_SZ_INSTALLED | LGRP_MEM_SZ_FREE, 70 LGRP_CONTENT_HIERARCHY | LGRP_CONTENT_DIRECT); 71 72 my $is_stale = lgrp_cookie_stale($\fIcookie\fR); 73 $stale = l->stale(); 74 75 lgrp_fini($\fIcookie\fR); 76 77 # The following is available for API version greater than 1: 78 my @lgrps = lgrp_resources($\fIcookie\fR, $\fIlgrp\fR, LGRP_RSRC_CPU); 79 80 # Get latencies from cookie 81 $latency = lgrp_latency_cookie($\fIcookie\fR, $\fIfrom\fR, $\fIto\fR); 82 .fi 83 84 .SH DESCRIPTION 85 .LP 86 This module provides access to the \fBliblgrp\fR(3LIB) library and to various 87 constants and functions defined in <\fBsys/lgrp_sys.h\fR>. It provides both the 88 procedural and object interface to the library. The procedural interface 89 requires (in most cases) passing around a transparent cookie. The object 90 interface hides all the cookie manipulations from the user. 91 .sp 92 .LP 93 Functions returning a scalar value indicate an error by returning \fBundef\fR. 94 The caller can examine the \fB$!\fR variable to get the error value. 95 .sp 96 .LP 97 Functions returning a list value return the number of elements in the list when 98 called in scalar context. In the event of error, the empty list is returned in 99 the array context and \fBundef\fR is returned in the scalar context. 100 .SS "Constants" 101 .LP 102 The constants are exported with \fB:CONSTANTS\fR or \fB:ALL\fR tags: 103 .sp 104 .in +2 105 .nf 106 use Sun::Solaris::Lgrp ':ALL'; 107 .fi 108 .in -2 109 110 .sp 111 .LP 112 or 113 .sp 114 .in +2 115 .nf 116 use Sun::Solaris::Lgrp ':CONSTANTS'; 117 .fi 118 .in -2 119 120 .sp 121 .LP 122 The following constants are available for use in Perl programs: 123 .br 124 .in +2 125 \fBLGRP_NONE\fR 126 .in -2 127 .br 128 .in +2 129 \fBLGRP_VER_CURRENT\fR 130 .in -2 131 .br 132 .in +2 133 \fBLGRP_VER_NONE\fR 134 .in -2 135 .br 136 .in +2 137 \fBLGRP_VIEW_CALLER\fR 138 .in -2 139 .br 140 .in +2 141 \fBLGRP_VIEW_OS\fR 142 .in -2 143 .br 144 .in +2 145 \fBLGRP_AFF_NONE\fR 146 .in -2 147 .br 148 .in +2 149 \fBLGRP_AFF_STRONG\fR 150 .in -2 151 .br 152 .in +2 153 \fBLGRP_AFF_WEAK\fR 154 .in -2 155 .br 156 .in +2 157 \fBLGRP_CONTENT_DIRECT\fR 158 .in -2 159 .br 160 .in +2 161 \fBLGRP_CONTENT_HIERARCHY\fR 162 .in -2 163 .br 164 .in +2 165 \fBLGRP_MEM_SZ_FREE\fR 166 .in -2 167 .br 168 .in +2 169 \fBLGRP_MEM_SZ_FREE\fR 170 .in -2 171 .br 172 .in +2 173 \fBLGRP_RSRC_CPU\fR (1) 174 .in -2 175 .br 176 .in +2 177 \fBLGRP_RSRC_MEM\fR (1) 178 .in -2 179 .br 180 .in +2 181 \fBLGRP_CONTENT_ALL\fR (1) 182 .in -2 183 .br 184 .in +2 185 \fBLGRP_LAT_CPU_TO_MEM\fR (1) 186 .in -2 187 .br 188 .in +2 189 \fBP_PID\fR 190 .in -2 191 .br 192 .in +2 193 \fBP_LWPID\fR 194 .in -2 195 .br 196 .in +2 197 \fBP_MYID\fR 198 .in -2 199 .sp 200 .LP 201 (1) Available for versions of the \fBliblgrp\fR(3LIB) API greater than 1. 202 .SS "Functions" 203 .LP 204 A detailed description of each function follows. Since this module is intended 205 to provide a Perl interface to the functions in \fBliblgrp\fR(3LIB), a very 206 short description is given for the corresponding functions in this module and a 207 reference is given to the complete description in the \fBliblgrp\fR manual 208 pages. Any differences or additional functionality in the Perl module are 209 highlighted and fully documented here. 210 .sp 211 .ne 2 212 .na 213 \fB\fBlgrp_init([LGRP_VIEW_CALLER | LGRP_VIEW_OS])\fR\fR 214 .ad 215 .sp .6 216 .RS 4n 217 This function initializes the lgroup interface and takes a snapshot of the 218 lgroup hierarchy with the given view. Given the view, \fBlgrp_init()\fR returns 219 a cookie representing this snapshot of the lgroup hierarchy. This cookie should 220 be used with other routines in the lgroup interface needing the lgroup 221 hierarchy. The \fBlgrp_fini()\fR function should be called with the cookie when 222 it is no longer needed. Unlike \fBlgrp_init\fR(3LGRP), \fBLGRP_VIEW_OS\fR is 223 assumed as the default if no view is provided. 224 .sp 225 Upon successful completion, \fBlgrp_init()\fR returns a cookie. Otherwise it 226 returns \fBundef\fR and sets \fB$!\fR to indicate the error. 227 .sp 228 See \fBlgrp_init\fR(3LGRP) for more information. 229 .RE 230 231 .sp 232 .ne 2 233 .na 234 \fB\fBlgrp_fini\fR($\fIcookie\fR)\fR 235 .ad 236 .sp .6 237 .RS 4n 238 This function takes a cookie, frees the snapshot of the lgroup hierarchy 239 created by \fBlgrp_init()\fR, and cleans up anything else set up by 240 \fBlgrp_init()\fR. After this function is called, the cookie returned by the 241 lgroup interface might no longer be valid and should not be used. 242 .sp 243 Upon successful completion, 1 is returned. Otherwise, \fBundef\fR is returned 244 and \fB$!\fR is set to indicate the error. 245 .sp 246 See \fBlgrp_fini\fR(3LGRP) for more information. 247 .RE 248 249 .sp 250 .ne 2 251 .na 252 \fB\fBlgrp_view\fR($\fIcookie\fR)\fR 253 .ad 254 .sp .6 255 .RS 4n 256 This function takes a cookie representing the snapshot of the lgroup hierarchy 257 and returns the snapshot's view of the lgroup hierarchy. 258 .sp 259 If the given view is \fBLGRP_VIEW_CALLER\fR, the snapshot contains only the 260 resources that are available to the caller (such as those with respect to 261 processor sets). When the view is \fBLGRP_VIEW_OS\fR, the snapshot contains 262 what is available to the operating system. 263 .sp 264 Upon successful completion, the function returns the view for the snapshot of 265 the lgroup hierarchy represented by the given cookie. Otherwise, \fBundef\fR 266 is returned and \fB$!\fR is set to indicate the error. 267 .sp 268 See \fBlgrp_view\fR(3LGRP) for more information. 269 .RE 270 271 .sp 272 .ne 2 273 .na 274 \fB\fBlgrp_home\fR($\fIidtype\fR, $\fIid\fR)\fR 275 .ad 276 .sp .6 277 .RS 4n 278 This function returns the home lgroup for the given process or thread. The 279 $\fIidtype\fR argument should be \fBP_PID\fR to specify a process and the 280 $\fIid\fR argument should be its process ID. Otherwise, the $\fIidtype\fR 281 argument should be \fBP_LWPID\fR to specify a thread and the $\fIid\fR argument 282 should be its LWP ID. The value \fBP_MYID\fR can be used for the $\fIid\fR 283 argument to specify the current process or thread. 284 .sp 285 Upon successful completion, \fBlgrp_home()\fR returns the ID of the home lgroup 286 of the specified process or thread. Otherwise, \fBundef\fR is returned and 287 \fB$!\fR is set to indicate the error. 288 .sp 289 See \fBlgrp_home\fR(3LGRP) for more information. 290 .RE 291 292 .sp 293 .ne 2 294 .na 295 \fB\fBlgrp_cookie_stale\fR($\fIcookie\fR)\fR 296 .ad 297 .sp .6 298 .RS 4n 299 Upon successful completion, this function returns whether the cookie is stale. 300 Otherwise, it returns \fBundef\fR and sets \fB$!\fR to indicate the error. 301 .sp 302 The \fBlgrp_cookie_stale()\fR function will fail with \fBEINVAL\fR if the 303 cookie is not valid. 304 .sp 305 See \fBlgrp_cookie_stale\fR(3LGRP) for more information. 306 .RE 307 308 .sp 309 .ne 2 310 .na 311 \fB\fBlgrp_cpus\fR($\fIcookie\fR, $\fIlgrp\fR, $\fIcontext\fR)\fR 312 .ad 313 .sp .6 314 .RS 4n 315 This function takes a cookie representing a snapshot of the lgroup hierarchy 316 and returns the list of CPUs in the lgroup specified by $\fIlgrp\fR. The 317 $\fIcontext\fR argument should be set to one of the following values to specify 318 whether the direct contents or everything in this lgroup including its children 319 should be returned: 320 .sp 321 .ne 2 322 .na 323 \fB\fBLGRP_CONTENT_HIERARCHY\fR\fR 324 .ad 325 .RS 26n 326 everything within this hierarchy 327 .RE 328 329 .sp 330 .ne 2 331 .na 332 \fB\fBLGRP_CONTENT_DIRECT\fR\fR 333 .ad 334 .RS 26n 335 directly contained in lgroup 336 .RE 337 338 When called in scalar context, \fBlgrp_cpus()\fR function returns the number of 339 CPUs contained in the specified lgroup. 340 .sp 341 In the event of error, \fBundef\fR is returned in scalar context and \fB$!\fR 342 is set to indicate the error. In list context, the empty list is returned and 343 \fB$!\fR is set. 344 .sp 345 See \fBlgrp_cpus\fR(3LGRP) for more information. 346 .RE 347 348 .sp 349 .ne 2 350 .na 351 \fB\fBlgrp_children\fR($\fIcookie\fR, $\fIlgrp\fR)\fR 352 .ad 353 .sp .6 354 .RS 4n 355 This function takes a cookie representing a snapshot of the lgroup hierarchy 356 and returns the list of lgroups that are children of the specified lgroup. 357 .sp 358 When called in scalar context, \fBlgrp_children()\fR returns the number of 359 children lgroups for the specified lgroup. 360 .sp 361 In the event of error, \fBundef\fR or empty list is returned and \fB$!\fR is 362 set to indicate the error. 363 .sp 364 See \fBlgrp_children\fR(3LGRP) for more information. 365 .RE 366 367 .sp 368 .ne 2 369 .na 370 \fB\fBlgrp_parents\fR($\fIcookie\fR, $\fIlgrp\fR)\fR 371 .ad 372 .sp .6 373 .RS 4n 374 This function takes a cookie representing a snapshot of the lgroup hierarchy 375 and returns the list of parents of the specified lgroup. 376 .sp 377 When called in scalar context, \fBlgrp_parents()\fR returns the number of 378 parent lgroups for the specified lgroup. 379 .sp 380 In the event of error, \fBundef\fR or an empty list is returned and \fB$!\fR is 381 set to indicate the error. 382 .sp 383 See \fBlgrp_parents\fR(3LGRP) for more information. 384 .RE 385 386 .sp 387 .ne 2 388 .na 389 \fB\fBlgrp_nlgrps\fR($\fIcookie\fR)\fR 390 .ad 391 .sp .6 392 .RS 4n 393 This function takes a cookie representing a snapshot of the lgroup hierarchy. 394 It returns the number of lgroups in the hierarchy, where the number is always 395 at least one. 396 .sp 397 In the event of error, \fBundef\fR is returned and \fB$!\fR is set to 398 \fBEINVAL\fR, indicating that the cookie is not valid. 399 .sp 400 See \fBlgrp_nlgrps\fR(3LGRP) for more information. 401 .RE 402 403 .sp 404 .ne 2 405 .na 406 \fB\fBlgrp_root\fR($\fIcookie\fR)\fR 407 .ad 408 .sp .6 409 .RS 4n 410 This function returns the root lgroup ID. 411 .sp 412 In the event of error, \fBundef\fR is returned and \fB$!\fR is set to 413 \fBEINVAL\fR, indicatng that the cookie is not valid. 414 .sp 415 See \fBlgrp_root\fR(3LGRP) for more information. 416 .RE 417 418 .sp 419 .ne 2 420 .na 421 \fB\fBlgrp_mem_size\fR($\fIcookie\fR, $\fIlgrp\fR, $\fItype\fR, 422 $\fIcontent\fR)\fR 423 .ad 424 .sp .6 425 .RS 4n 426 This function takes a cookie representing a snapshot of the lgroup hierarchy. 427 The function returns the memory size of the given lgroup in bytes. The 428 $\fItype\fR argument should be set to one of the following values: 429 .sp 430 .ne 2 431 .na 432 \fB\fBLGRP_MEM_SZ_FREE\fR\fR 433 .ad 434 .RS 25n 435 free memory 436 .RE 437 438 .sp 439 .ne 2 440 .na 441 \fB\fBLGRP_MEM_SZ_INSTALLED\fR\fR 442 .ad 443 .RS 25n 444 installed memory 445 .RE 446 447 The $\fIcontent\fR argument should be set to one of the following values to 448 specify whether the direct contents or everything in this lgroup including its 449 children should be returned: 450 .sp 451 .ne 2 452 .na 453 \fB\fBLGRP_CONTENT_HIERARCHY\fR\fR 454 .ad 455 .RS 26n 456 Return everything within this hierarchy. 457 .RE 458 459 .sp 460 .ne 2 461 .na 462 \fB\fBLGRP_CONTENT_DIRECT\fR\fR 463 .ad 464 .RS 26n 465 Return that which is directly contained in this lgroup. 466 .RE 467 468 The total sizes include all the memory in the lgroup including its children, 469 while the others reflect only the memory contained directly in the given 470 lgroup. 471 .sp 472 Upon successful completion, the size in bytes is returned. Otherwise, 473 \fBundef\fR is returned and \fB$!\fR is set to indicate the error. 474 .sp 475 See \fBlgrp_mem_size\fR(3LGRP) for more information. 476 .RE 477 478 .sp 479 .ne 2 480 .na 481 \fB\fBlgrp_version\fR([$\fIversion\fR])\fR 482 .ad 483 .sp .6 484 .RS 4n 485 This function takes an interface version number, $\fIversion\fR, as an argument 486 and returns an lgroup interface version. The $\fIversion\fR argument should be 487 the value of \fBLGRP_VER_CURRENT\fR or \fBLGRP_VER_NONE\fR to find out the 488 current lgroup interface version on the running system. 489 .sp 490 If $\fIversion\fR is still supported by the implementation, then 491 \fBlgrp_version()\fR returns the requested version. If \fBLGRP_VER_NONE\fR is 492 returned, the implementation cannot support the requested version. 493 .sp 494 If $\fIversion\fR is \fBLGRP_VER_NONE\fR, \fBlgrp_version()\fR returns the 495 current version of the library. 496 .sp 497 The following example tests whether the version of the interface used by the 498 caller is supported: 499 .sp 500 .in +2 501 .nf 502 lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or 503 die("Built with unsupported lgroup interface"); 504 .fi 505 .in -2 506 507 See \fBlgrp_version\fR(3LGRP) for more information. 508 .RE 509 510 .sp 511 .ne 2 512 .na 513 \fB\fBlgrp_affinity_set\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR, 514 $\fIaffinity\fR)\fR 515 .ad 516 .sp .6 517 .RS 4n 518 This function sets the affinity that the LWP or set of LWPs specified by 519 $\fIidtype\fR and $\fIid\fR have for the given lgroup. The lgroup affinity can 520 be set to \fBLGRP_AFF_STRONG\fR, \fBLGRP_AFF_WEAK\fR, or \fBLGRP_AFF_NONE\fR. 521 .sp 522 If the $\fIidtype\fR is \fBP_PID\fR, the affinity is retrieved for one of the 523 LWPs in the process or set for all the LWPs of the process with process ID 524 (PID) $\fIid\fR. The affinity is retrieved or set for the LWP of the current 525 process with LWP ID $\fIid\fR if $\fIidtype\fR is \fBP_LWPID\fR. If $\fIid\fR 526 is \fBP_MYID\fR, then the current LWP or process is specified. 527 .sp 528 There are different levels of affinity that can be specified by a thread for a 529 particuliar lgroup. The levels of affinity are the following from strongest to 530 weakest: 531 .sp 532 .ne 2 533 .na 534 \fB\fBLGRP_AFF_STRONG\fR\fR 535 .ad 536 .RS 19n 537 strong affinity 538 .RE 539 540 .sp 541 .ne 2 542 .na 543 \fB\fBLGRP_AFF_WEAK\fR\fR 544 .ad 545 .RS 19n 546 weak affinity 547 .RE 548 549 .sp 550 .ne 2 551 .na 552 \fB\fBLGRP_AFF_NONE\fR\fR 553 .ad 554 .RS 19n 555 no affinity 556 .RE 557 558 Upon successful completion, \fBlgrp_affinity_set()\fR returns 1. Otherwise, it 559 returns \fBundef\fR and set \fB$!\fR to indicate the error. 560 .sp 561 See \fBlgrp_affinity_set\fR(3LGRP) for more information. 562 .RE 563 564 .sp 565 .ne 2 566 .na 567 \fB\fBlgrp_affinity_get\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR)\fR 568 .ad 569 .sp .6 570 .RS 4n 571 This function returns the affinity that the LWP has to a given lgroup. 572 .sp 573 See \fBlgrp_affinity_get\fR(3LGRP) for more information. 574 .RE 575 576 .sp 577 .ne 2 578 .na 579 \fB\fBlgrp_latency_cookie\fR($\fIcookie\fR, $\fIfrom\fR, $\fIto\fR, 580 [$\fIbetween\fR=\fBLGRP_LAT_CPU_TO_MEM\fR])\fR 581 .ad 582 .sp .6 583 .RS 4n 584 This function takes a cookie representing a snapshot of the lgroup hierarchy 585 and returns the latency value between a hardware resource in the $\fIfrom\fR 586 lgroup to a hardware resource in the $\fIto\fR lgroup. If $\fIfrom\fR is the 587 same lgroup as $\fIto\fR, the latency value within that lgroup is returned. 588 .sp 589 The optional $\fIbetween\fR argument should be set to \fBLGRP_LAT_CPU_TO_MEM\fR 590 to specify between which hardware resources the latency should be measured. The 591 only valid value is \fBLGRP_LAT_CPU_TO_MEM\fR, which represents latency from 592 CPU to memory. 593 .sp 594 Upon successful completion, \fBlgrp_latency_cookie()\fR return 1. Otherwise, 595 it returns \fBundef\fR and set \fB$!\fR to indicate the error. For LGRP API 596 version 1, the \fBlgrp_latency_cookie()\fR is an alias for 597 \fBlgrp_latency.()\fR 598 .sp 599 See \fBlgrp_latency_cookie\fR(3LGRP) for more information. 600 .RE 601 602 .sp 603 .ne 2 604 .na 605 \fB\fBlgrp_latency\fR($\fIfrom\fR, $\fIto\fR)\fR 606 .ad 607 .sp .6 608 .RS 4n 609 This function is similar to the \fBlgrp_latency_cookie()\fR function, but 610 returns the latency between the given lgroups at the given instant in time. 611 Since lgroups can be freed and reallocated, this function might not be able to 612 provide a consistent answer across calls. For that reason, 613 \fBlgrp_latency_cookie()\fR should be used in its place. 614 .sp 615 See \fBlgrp_latency\fR(3LGRP) for more information. 616 .RE 617 618 .sp 619 .ne 2 620 .na 621 \fB\fBlgrp_resources\fR($\fIcookie\fR, $\fIlgrp\fR, $\fItype\fR)\fR 622 .ad 623 .sp .6 624 .RS 4n 625 This function returns the list of lgroups directly containing resources of the 626 specified type. The resources are represented by a set of lgroups in which each 627 lgroup directly contains CPU and/or memory resources. 628 .sp 629 The \fItype\fR can be specified as: 630 .sp 631 .ne 2 632 .na 633 \fB\fBLGRP_RSRC_CPU\fR\fR 634 .ad 635 .RS 17n 636 CPU resources 637 .RE 638 639 .sp 640 .ne 2 641 .na 642 \fB\fBLGRP_RSRC_MEM\fR\fR 643 .ad 644 .RS 17n 645 memory resources 646 .RE 647 648 In the event of error, \fBundef\fR or an empty list is returned and \fB$!\fR is 649 set to indicate the error. 650 .sp 651 This function is available only for API version 2 and returns \fBundef\fR or an 652 empty list for API version 1 and sets \fB$!\fR to \fBEINVAL\fR. 653 .sp 654 See \fBlgrp_resources\fR(3LGRP) for more information. 655 .RE 656 657 .sp 658 .ne 2 659 .na 660 \fB\fBlgrp_lgrps\fR($\fIcookie\fR, [$\fIlgrp\fR])\fR 661 .ad 662 .sp .6 663 .RS 4n 664 This function returns a list of all lgroups in a hierarchy starting from 665 $\fIlgrp\fR. If $\fIlgrp\fR is not specified, uses the value of 666 \fBlgrp_root\fR($\fIcookie\fR). This function returns the empty list on 667 failure. 668 .sp 669 When called in scalar context, this function returns the total number of 670 lgroups in the system. 671 .RE 672 673 .sp 674 .ne 2 675 .na 676 \fB\fBlgrp_leaves\fR($\fIcookie\fR, [$\fIlgrp\fR])\fR 677 .ad 678 .sp .6 679 .RS 4n 680 This function returns a list of all leaf lgroups in a hierarchy starting from 681 $\fIlgrp\fR. If $\fIlgrp\fR is not specified, this function uses the value of 682 \fBlgrp_root\fR($\fIcookie\fR). It returns \fBundef\fR or an empty list on 683 failure. 684 .sp 685 When called in scalar context, this function returns the total number of leaf 686 lgroups in the system. 687 .RE 688 689 .sp 690 .ne 2 691 .na 692 \fB\fBlgrp_isleaf\fR($\fIcookie\fR, $\fIlgrp\fR)\fR 693 .ad 694 .sp .6 695 .RS 4n 696 This function returns True if $\fIlgrp\fR is a leaf (has no children). 697 Otherwise it returns False. 698 .RE 699 700 .SS "Object methods" 701 .ne 2 702 .na 703 \fB\fBnew\fR([$\fIview\fR])\fR 704 .ad 705 .sp .6 706 .RS 4n 707 This method creates a new \fBSun::Solaris::Lgrp\fR object. An optional argument 708 is passed to the \fBlgrp_init()\fR function. By default this method uses 709 \fBLGRP_VIEW_OS\fR. 710 .RE 711 712 .sp 713 .ne 2 714 .na 715 \fB\fBcookie()\fR\fR 716 .ad 717 .sp .6 718 .RS 4n 719 This method returns a transparent cookie that can be passed to functions 720 accepting the cookie. 721 .RE 722 723 .sp 724 .ne 2 725 .na 726 \fB\fBversion\fR([$\fIversion\fR])\fR 727 .ad 728 .sp .6 729 .RS 4n 730 Without the argument, this method returns the current version of the 731 \fBliblgrp\fR(3LIB) library. This method is a wrapper for \fBlgrp_version()\fR 732 with \fBLGRP_VER_NONE\fR as the default version argument. 733 .RE 734 735 .sp 736 .ne 2 737 .na 738 \fB\fBstale()\fR\fR 739 .ad 740 .sp .6 741 .RS 4n 742 This method returns T if the lgroup information in the object is stale and F 743 otherwise. It is a wrapper for \fBlgrp_cookie_stale()\fR. 744 .RE 745 746 .sp 747 .ne 2 748 .na 749 \fB\fBview()\fR\fR 750 .ad 751 .sp .6 752 .RS 4n 753 This method returns the snapshot's view of the lgroup hierarchy. It is a 754 wrapper for \fBlgrp_view()\fR. 755 .RE 756 757 .sp 758 .ne 2 759 .na 760 \fB\fBroot()\fR\fR 761 .ad 762 .sp .6 763 .RS 4n 764 This method returns the root lgroup. It is a wrapper for \fBlgrp_root()\fR. 765 .RE 766 767 .sp 768 .ne 2 769 .na 770 \fB\fBchildren\fR($\fIlgrp\fR)\fR 771 .ad 772 .sp .6 773 .RS 4n 774 This method returns the list of lgroups that are children of the specified 775 lgroup. It is a wrapper for \fBlgrp_children()\fR. 776 .RE 777 778 .sp 779 .ne 2 780 .na 781 \fB\fBparents\fR($\fIlgrp\fR)\fR 782 .ad 783 .sp .6 784 .RS 4n 785 This method returns the list of lgroups that are parents of the specified 786 lgroup. It is a wrapper for \fBlgrp_parents()\fR. 787 .RE 788 789 .sp 790 .ne 2 791 .na 792 \fB\fBnlgrps()\fR\fR 793 .ad 794 .sp .6 795 .RS 4n 796 This method returns the number of lgroups in the hierarchy. It is a wrapper for 797 \fBlgrp_nlgrps()\fR. 798 .RE 799 800 .sp 801 .ne 2 802 .na 803 \fB\fBmem_size\fR($\fIlgrp\fR, $\fItype\fR, $\fIcontent\fR)\fR 804 .ad 805 .sp .6 806 .RS 4n 807 This method returns the memory size of the given lgroup in bytes. It is a 808 wrapper for \fBlgrp_mem_size()\fR. 809 .RE 810 811 .sp 812 .ne 2 813 .na 814 \fB\fBcpus\fR($\fIlgrp\fR, $\fIcontext\fR)\fR 815 .ad 816 .sp .6 817 .RS 4n 818 This method returns the list of CPUs in the lgroup specified by $lgrp. It is a 819 wrapper for \fBlgrp_cpus()\fR. 820 .RE 821 822 .sp 823 .ne 2 824 .na 825 \fB\fBresources\fR($\fIlgrp\fR, $\fItype\fR)\fR 826 .ad 827 .sp .6 828 .RS 4n 829 This method returns the list of lgroups directly containing resources of the 830 specified type. It is a wrapper for \fBlgrp_resources()\fR. 831 .RE 832 833 .sp 834 .ne 2 835 .na 836 \fB\fBhome\fR($\fIidtype\fR, $\fIid\fR)\fR 837 .ad 838 .sp .6 839 .RS 4n 840 This method returns the home lgroup for the given process or thread. It is a 841 wrapper for \fBlgrp_home()\fR. 842 .RE 843 844 .sp 845 .ne 2 846 .na 847 \fB\fBaffinity_get\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR)\fR 848 .ad 849 .sp .6 850 .RS 4n 851 This method returns the affinity that the LWP has to a given lgrp. It is a 852 wrapper for \fBlgrp_affinity_get()\fR. 853 .RE 854 855 .sp 856 .ne 2 857 .na 858 \fB\fBaffinity_set\fR($\fIidtype\fR, $\fIid\fR, $\fIlgrp\fR, 859 $\fIaffinity\fR)\fR 860 .ad 861 .sp .6 862 .RS 4n 863 This method sets the affinity that the LWP or set of LWPs specified by 864 $\fIidtype\fR and $\fIid\fR have for the given lgroup. It is a wrapper for 865 lgrp_affinity_set. 866 .RE 867 868 .sp 869 .ne 2 870 .na 871 \fB\fBlgrps\fR([$\fIlgrp\fR])\fR 872 .ad 873 .sp .6 874 .RS 4n 875 This method returns list of all lgroups in a hierarchy starting from 876 $\fIlgrp\fR or the \fBlgrp_root()\fR if $\fIlgrp\fR is not specified. It is a 877 wrapper for \fBlgrp_lgrps()\fR. 878 .RE 879 880 .sp 881 .ne 2 882 .na 883 \fB\fBleaves\fR([$\fIlgrp\fR])\fR 884 .ad 885 .sp .6 886 .RS 4n 887 This method returns a list of all leaf lgroups in a hierarchy starting from 888 $\fIlgrp\fR. If $\fIlgrp\fR is not specified, this method uses the value of 889 \fBlgrp_root()\fR. It is a wrapper for \fBlgrp_leaves()\fR. 890 .RE 891 892 .sp 893 .ne 2 894 .na 895 \fB\fBisleaf\fR($\fIlgrp\fR)\fR 896 .ad 897 .sp .6 898 .RS 4n 899 This method returns True if $\fIlgrp\fR is leaf (has no children) and False 900 otherwise. It is a wrapper for \fBlgrp_isleaf()\fR. 901 .RE 902 903 .sp 904 .ne 2 905 .na 906 \fB\fBlatency\fR($\fIfrom\fR, $\fIto\fR)\fR 907 .ad 908 .sp .6 909 .RS 4n 910 This method returns the latency value between a hardware resource in the 911 $\fIfrom\fR lgroup to a hardware resource in the $\fIto\fR lgroup. It uses 912 \fBlgrp_latency()\fR for version 1 of \fBliblgrp\fR and 913 \fBlgrp_latency_cookie()\fR for newer versions. 914 .RE 915 916 .SS "Exports" 917 .LP 918 By default nothing is exported from this module. The following tags can be used 919 to selectively import constants and functions defined in this module: 920 .sp 921 .ne 2 922 .na 923 \fB\fB:LGRP_CONSTANTS\fR\fR 924 .ad 925 .RS 19n 926 \fBLGRP_AFF_NONE\fR, \fBLGRP_AFF_STRONG\fR, \fBLGRP_AFF_WEAK\fR, 927 \fBLGRP_CONTENT_DIRECT\fR, \fBLGRP_CONTENT_HIERARCHY\fR, 928 \fBLGRP_MEM_SZ_FREE\fR, \fBLGRP_MEM_SZ_INSTALLED\fR, \fBLGRP_VER_CURRENT\fR, 929 \fBLGRP_VER_NONE\fR, \fBLGRP_VIEW_CALLER\fR, \fBLGRP_VIEW_OS\fR, 930 \fBLGRP_NONE\fR, \fBLGRP_RSRC_CPU\fR, \fBLGRP_RSRC_MEM\fR, 931 \fBLGRP_CONTENT_ALL\fR, \fBLGRP_LAT_CPU_TO_MEM\fR 932 .RE 933 934 .sp 935 .ne 2 936 .na 937 \fB\fB:PROC_CONSTANTS\fR\fR 938 .ad 939 .RS 19n 940 \fBP_PID\fR, \fBP_LWPID\fR, \fBP_MYID\fR 941 .RE 942 943 .sp 944 .ne 2 945 .na 946 \fB\fB:CONSTANTS\fR\fR 947 .ad 948 .RS 19n 949 \fB:LGRP_CONSTANTS\fR, \fB:PROC_CONSTANTS\fR 950 .RE 951 952 .sp 953 .ne 2 954 .na 955 \fB\fB:FUNCTIONS\fR\fR 956 .ad 957 .RS 19n 958 \fBlgrp_affinity_get()\fR, \fBlgrp_affinity_set()\fR, \fBlgrp_children()\fR, 959 \fBlgrp_cookie_stale()\fR, \fBlgrp_cpus()\fR, \fBlgrp_fini()\fR, 960 \fBlgrp_home()\fR, \fBlgrp_init()\fR, \fBlgrp_latency()\fR, 961 \fBlgrp_latency_cookie()\fR, \fBlgrp_mem_size()\fR, \fBlgrp_nlgrps()\fR, 962 \fBlgrp_parents()\fR, \fBlgrp_root()\fR, \fBlgrp_version()\fR, 963 \fBlgrp_view()\fR, \fBlgrp_resources()\fR, \fBlgrp_lgrps()\fR, 964 \fBlgrp_leaves()\fR, \fBlgrp_isleaf()\fR 965 .RE 966 967 .sp 968 .ne 2 969 .na 970 \fB\fB:ALL\fR\fR 971 .ad 972 .RS 19n 973 \fB:CONSTANTS\fR, \fB:FUNCTIONS\fR 974 .RE 975 976 .SS "Error values" 977 .LP 978 The functions in this module return \fBundef\fR or an empty list when an 979 underlying library function fails. The \fB$!\fR is set to provide more 980 information values for the error. The following error codes are possible: 981 .sp 982 .ne 2 983 .na 984 \fB\fBEINVAL\fR\fR 985 .ad 986 .RS 10n 987 The value supplied is not valid. 988 .RE 989 990 .sp 991 .ne 2 992 .na 993 \fB\fBENOMEM\fR\fR 994 .ad 995 .RS 10n 996 There was not enough system memory to complete an operation. 997 .RE 998 999 .sp 1000 .ne 2 1001 .na 1002 \fB\fBEPERM\fR\fR 1003 .ad 1004 .RS 10n 1005 The effective user of the calling process does not have appropriate privileges, 1006 and its real or effective user ID does not match the real or effective user ID 1007 of one of the threads. 1008 .RE 1009 1010 .sp 1011 .ne 2 1012 .na 1013 \fB\fBESRCH\fR\fR 1014 .ad 1015 .RS 10n 1016 The specified process or thread was not found. 1017 .RE 1018 1019 .SS "Difference in the API versions" 1020 .LP 1021 The \fBliblgrp\fR(3LIB) library is versioned. The exact version that was used 1022 to compile a module is available through the \fBlgrp_version()\fR function. 1023 .sp 1024 .LP 1025 Version 2 of the \fBlgrp_user\fR API introduced the following constants and 1026 functions not present in version 1: 1027 .br 1028 .in +2 1029 \fBLGRP_RSRC_CPU\fR constant 1030 .in -2 1031 .br 1032 .in +2 1033 \fBLGRP_RSRC_MEM\fR constant 1034 .in -2 1035 .br 1036 .in +2 1037 \fBLGRP_CONTENT_ALL\fR constant 1038 .in -2 1039 .br 1040 .in +2 1041 \fBLGRP_LAT_CPU_TO_MEM\fR constant 1042 .in -2 1043 .br 1044 .in +2 1045 \fBlgrp_resources()\fR function 1046 .in -2 1047 .br 1048 .in +2 1049 \fBlgrp_latency_cookie()\fR function 1050 .in -2 1051 .sp 1052 .LP 1053 The \fBLGRP_RSRC_CPU\fR and \fBLGRP_RSRC_MEM\fR constants are not defined for 1054 version 1. The \fBlgrp_resources()\fR function is defined for version 1 but 1055 always returns an empty list. The \fBlgrp_latency_cookie()\fR function is an 1056 alias for \fBlgrp_latency()\fR for version 1. 1057 .SH ATTRIBUTES 1058 .LP 1059 See \fBattributes\fR(5) for descriptions of the following attributes: 1060 .sp 1061 1062 .sp 1063 .TS 1064 box; 1065 c | c 1066 l | l . 1067 ATTRIBUTE TYPE ATTRIBUTE VALUE 1068 _ 1069 Interface Stability Unstable 1070 .TE 1071 1072 .SH SEE ALSO 1073 .LP 1074 \fBlgrp_affinity_get\fR(3LGRP), \fBlgrp_affinity_set\fR(3LGRP), 1075 \fBlgrp_children\fR(3LGRP), \fBlgrp_cookie_stale\fR(3LGRP), 1076 \fBlgrp_cpus\fR(3LGRP), \fBlgrp_fini\fR(3LGRP), \fBlgrp_home\fR(3LGRP), 1077 \fBlgrp_init\fR(3LGRP), \fBlgrp_latency\fR(3LGRP), 1078 \fBlgrp_latency_cookie\fR(3LGRP), \fBlgrp_mem_size\fR(3LGRP), 1079 \fBlgrp_nlgrps\fR(3LGRP), \fBlgrp_parents\fR(3LGRP), 1080 \fBlgrp_resources\fR(3LGRP), \fBlgrp_root\fR(3LGRP), \fBlgrp_version\fR(3LGRP), 1081 \fBlgrp_view\fR(3LGRP), \fBliblgrp\fR(3LIB), \fBattributes\fR(5)