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