1Lgrp(3PERL) Perl Library Functions Lgrp(3PERL)
2
3
4
6 Lgrp - Perl interface to Solaris liblgrp library
7
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
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 succesful 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 indi‐
212 cate 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 everything within this hierarchy
229
230
231 LGRP_CONTENT_DIRECT directly contained in lgroup
232
233 When called in scalar context, lgrp_cpus() function returns the
234 number of CPUs contained in the specified lgroup.
235
236 In the event of error, undef is returned in scalar context and $!
237 is set to indicate the error. In list context, the empty list is
238 returned and $! is set.
239
240 See lgrp_cpus(3LGRP) for more information.
241
242
243 lgrp_children($cookie, $lgrp)
244
245 This function takes a cookie representing a snapshot of the lgroup
246 hierarchy and returns the list of lgroups that are children of the
247 specified lgroup.
248
249 When called in scalar context, lgrp_children() returns the number
250 of children lgroups for the specified lgroup.
251
252 In the event of error, undef or empty list is returned and $! is
253 set to indicate the error.
254
255 See lgrp_children(3LGRP) for more information.
256
257
258 lgrp_parents($cookie, $lgrp)
259
260 This function takes a cookie representing a snapshot of the lgroup
261 hierarchy and returns the list of parents of the specified lgroup.
262
263 When called in scalar context, lgrp_parents() returns the number of
264 parent lgroups for the specified lgroup.
265
266 In the event of error, undef or an empty list is returned and $! is
267 set to indicate the error.
268
269 See lgrp_parents(3LGRP) for more information.
270
271
272 lgrp_nlgrps($cookie)
273
274 This function takes a cookie representing a snapshot of the lgroup
275 hierarchy. It returns the number of lgroups in the hierarchy, where
276 the number is always at least one.
277
278 In the event of error, undef is returned and $! is set to EINVAL,
279 indicating that the cookie is not valid.
280
281 See lgrp_nlgrps(3LGRP) for more information.
282
283
284 lgrp_root($cookie)
285
286 This function returns the root lgroup ID.
287
288 In the event of error, undef is returned and $! is set to EINVAL,
289 indicatng that the cookie is not valid.
290
291 See lgrp_root(3LGRP) for more information.
292
293
294 lgrp_mem_size($cookie, $lgrp, $type, $content)
295
296 This function takes a cookie representing a snapshot of the lgroup
297 hierarchy. The function returns the memory size of the given lgroup
298 in bytes. The $type argument should be set to one of the following
299 values:
300
301 LGRP_MEM_SZ_FREE free memory
302
303
304 LGRP_MEM_SZ_INSTALLED installed memory
305
306 The $content argument should be set to one of the following values
307 to specify whether the direct contents or everything in this lgroup
308 including its children should be returned:
309
310 LGRP_CONTENT_HIERARCHY Return everything within this hierarchy.
311
312
313 LGRP_CONTENT_DIRECT Return that which is directly contained
314 in this lgroup.
315
316 The total sizes include all the memory in the lgroup including its
317 children, while the others reflect only the memory contained
318 directly in the given lgroup.
319
320 Upon successful completion, the size in bytes is returned. Other‐
321 wise, undef is returned and $! is set to indicate the error.
322
323 See lgrp_mem_size(3LGRP) for more information.
324
325
326 lgrp_version([$version])
327
328 This function takes an interface version number, $version, as an
329 argument and returns an lgroup interface version. The $version
330 argument should be the value of LGRP_VER_CURRENT or LGRP_VER_NONE
331 to find out the current lgroup interface version on the running
332 system.
333
334 If $version is still supported by the implementation, then
335 lgrp_version() returns the requested version. If LGRP_VER_NONE is
336 returned, the implementation cannot support the requested version.
337
338 If $version is LGRP_VER_NONE, lgrp_version() returns the current
339 version of the library.
340
341 The following example tests whether the version of the interface
342 used by the caller is supported:
343
344 lgrp_version(LGRP_VER_CURRENT) == LGRP_VER_CURRENT or
345 die("Built with unsupported lgroup interface");
346
347 See lgrp_version(3LGRP) for more information.
348
349
350 lgrp_affinity_set($idtype, $id, $lgrp, $affinity)
351
352 This function sets the affinity that the LWP or set of LWPs speci‐
353 fied by $idtype and $id have for the given lgroup. The lgroup
354 affinity can be set to LGRP_AFF_STRONG, LGRP_AFF_WEAK, or
355 LGRP_AFF_NONE.
356
357 If the $idtype is P_PID, the affinity is retrieved for one of the
358 LWPs in the process or set for all the LWPs of the process with
359 process ID (PID) $id. The affinity is retrieved or set for the LWP
360 of the current process with LWP ID $id if $idtype is P_LWPID. If
361 $id is P_MYID, then the current LWP or process is specified.
362
363 There are different levels of affinity that can be specified by a
364 thread for a particuliar lgroup. The levels of affinity are the
365 following from strongest to weakest:
366
367 LGRP_AFF_STRONG strong affinity
368
369
370 LGRP_AFF_WEAK weak affinity
371
372
373 LGRP_AFF_NONE no affinity
374
375 Upon successful completion, lgrp_affinity_set() returns 1. Other‐
376 wise, it returns undef and set $! to indicate the error.
377
378 See lgrp_affinity_set(3LGRP) for more information.
379
380
381 lgrp_affinity_get($idtype, $id, $lgrp)
382
383 This function returns the affinity that the LWP has to a given
384 lgroup.
385
386 See lgrp_affinity_get(3LGRP) for more information.
387
388
389 lgrp_latency_cookie($cookie, $from, $to,
390 [$between=LGRP_LAT_CPU_TO_MEM])
391
392 This function takes a cookie representing a snapshot of the lgroup
393 hierarchy and returns the latency value between a hardware resource
394 in the $from lgroup to a hardware resource in the $to lgroup. If
395 $from is the same lgroup as $to, the latency value within that
396 lgroup is returned.
397
398 The optional $between argument should be set to LGRP_LAT_CPU_TO_MEM
399 to specify between which hardware resources the latency should be
400 measured. The only valid value is LGRP_LAT_CPU_TO_MEM, which repre‐
401 sents latency from CPU to memory.
402
403 Upon successful completion, lgrp_latency_cookie() return 1. Other‐
404 wise, it returns undef and set $! to indicate the error. For LGRP
405 API version 1, the lgrp_latency_cookie() is an alias for
406 lgrp_latency.()
407
408 See lgrp_latency_cookie(3LGRP) for more information.
409
410
411 lgrp_latency($from, $to)
412
413 This function is similiar to the lgrp_latency_cookie() function,
414 but returns the latency between the given lgroups at the given
415 instant in time. Since lgroups can be freed and reallocated, this
416 function might not be able to provide a consistent answer across
417 calls. For that reason, lgrp_latency_cookie() should be used in its
418 place.
419
420 See lgrp_latency(3LGRP) for more information.
421
422
423 lgrp_resources($cookie, $lgrp, $type)
424
425 This function returns the list of lgroups directly containing
426 resources of the specified type. The resources are represented by a
427 set of lgroups in which each lgroup directly contains CPU and/or
428 memory resources.
429
430 The type can be specified as:
431
432 LGRP_RSRC_CPU CPU resources
433
434
435 LGRP_RSRC_MEM memory resources
436
437 In the event of error, undef or an empty list is returned and $! is
438 set to indicate the error.
439
440 This function is available only for API version 2 and returns undef
441 or an empty list for API version 1 and sets $! to EINVAL.
442
443 See lgrp_resources(3LGRP) for more information.
444
445
446 lgrp_lgrps($cookie, [$lgrp])
447
448 This function returns a list of all lgroups in a hierarchy starting
449 from $lgrp. If $lgrp is not specified, uses the value of
450 lgrp_root($cookie). This function returns the empty list on fail‐
451 ure.
452
453 When called in scalar context, this function returns the total num‐
454 ber of lgroups in the system.
455
456
457 lgrp_leaves($cookie, [$lgrp])
458
459 This function returns a list of all leaf lgroups in a hierarchy
460 starting from $lgrp. If $lgrp is not specified, this function uses
461 the value of lgrp_root($cookie). It returns undef or an empty list
462 on failure.
463
464 When called in scalar context, this function returns the total num‐
465 ber of leaf lgroups in the system.
466
467
468 lgrp_isleaf($cookie, $lgrp)
469
470 This function returns True if $lgrp is a leaf (has no children).
471 Otherwise it returns False.
472
473
474 Object methods
475 new([$view])
476
477 This method creates a new Sun::Solaris::Lgrp object. An optional
478 argument is passed to the lgrp_init() function. By default this
479 method uses LGRP_VIEW_OS.
480
481
482 cookie()
483
484 This method returns a transparent cookie that can be passed to
485 functions accepting the cookie.
486
487
488 version([$version])
489
490 Without the argument, this method returns the current version of
491 the liblgrp(3LIB) library. This method is a wrapper for lgrp_ver‐
492 sion() with LGRP_VER_NONE as the default version argument.
493
494
495 stale()
496
497 This method returns T if the lgroup information in the object is
498 stale and F otherwise. It is a wrapper for lgrp_cookie_stale().
499
500
501 view()
502
503 This method returns the snapshot's view of the lgroup hierarchy. It
504 is a wrapper for lgrp_view().
505
506
507 root()
508
509 This method returns the root lgroup. It is a wrapper for
510 lgrp_root().
511
512
513 children($lgrp)
514
515 This method returns the list of lgroups that are children of the
516 specified lgroup. It is a wrapper for lgrp_children().
517
518
519 parents($lgrp)
520
521 This method returns the list of lgroups that are parents of the
522 specified lgroup. It is a wrapper for lgrp_parents().
523
524
525 nlgrps()
526
527 This method returns the number of lgroups in the hierarchy. It is a
528 wrapper for lgrp_nlgrps().
529
530
531 mem_size($lgrp, $type, $content)
532
533 This method returns the memory size of the given lgroup in bytes.
534 It is a wrapper for lgrp_mem_size().
535
536
537 cpus($lgrp, $context)
538
539 This method returns the list of CPUs in the lgroup specified by
540 $lgrp. It is a wrapper for lgrp_cpus().
541
542
543 resources($lgrp, $type)
544
545 This method returns the list of lgroups directly containing
546 resources of the specified type. It is a wrapper for
547 lgrp_resources().
548
549
550 home($idtype, $id)
551
552 This method returns the home lgroup for the given process or
553 thread. It is a wrapper for lgrp_home().
554
555
556 affinity_get($idtype, $id, $lgrp)
557
558 This method returns the affinity that the LWP has to a given lgrp.
559 It is a wrapper for lgrp_affinity_get().
560
561
562 affinity_set($idtype, $id, $lgrp, $affinity)
563
564 This method sets the affinity that the LWP or set of LWPs specified
565 by $idtype and $id have for the given lgroup. It is a wrapper for
566 lgrp_affinity_set.
567
568
569 lgrps([$lgrp])
570
571 This method returns list of all lgroups in a hierarchy starting
572 from $lgrp or the lgrp_root() if $lgrp is not specified. It is a
573 wrapper for lgrp_lgrps().
574
575
576 leaves([$lgrp])
577
578 This method returns a list of all leaf lgroups in a hierarchy
579 starting from $lgrp. If $lgrp is not specified, this method uses
580 the value of lgrp_root(). It is a wrapper for lgrp_leaves().
581
582
583 isleaf($lgrp)
584
585 This method returns True if $lgrp is leaf (has no children) and
586 False otherwise. It is a wrapper for lgrp_isleaf().
587
588
589 latency($from, $to)
590
591 This method returns the latency value between a hardware resource
592 in the $from lgroup to a hardware resource in the $to lgroup. It
593 uses lgrp_latency() for version 1 of liblgrp and
594 lgrp_latency_cookie() for newer versions.
595
596
597 Exports
598 By default nothing is exported from this module. The following tags can
599 be used to selectively import constants and functions defined in this
600 module:
601
602 :LGRP_CONSTANTS LGRP_AFF_NONE, LGRP_AFF_STRONG, LGRP_AFF_WEAK,
603 LGRP_CONTENT_DIRECT, LGRP_CONTENT_HIERARCHY,
604 LGRP_MEM_SZ_FREE, LGRP_MEM_SZ_INSTALLED,
605 LGRP_VER_CURRENT, LGRP_VER_NONE, LGRP_VIEW_CALLER,
606 LGRP_VIEW_OS, LGRP_NONE, LGRP_RSRC_CPU,
607 LGRP_RSRC_MEM, LGRP_CONTENT_ALL, LGRP_LAT_CPU_TO_MEM
608
609
610 :PROC_CONSTANTS P_PID, P_LWPID, P_MYID
611
612
613 :CONSTANTS :LGRP_CONSTANTS, :PROC_CONSTANTS
614
615
616 :FUNCTIONS lgrp_affinity_get(), lgrp_affinity_set(), lgrp_chil‐
617 dren(), lgrp_cookie_stale(), lgrp_cpus(),
618 lgrp_fini(), lgrp_home(), lgrp_init(),
619 lgrp_latency(), lgrp_latency_cookie(),
620 lgrp_mem_size(), lgrp_nlgrps(), lgrp_parents(),
621 lgrp_root(), lgrp_version(), lgrp_view(),
622 lgrp_resources(), lgrp_lgrps(), lgrp_leaves(),
623 lgrp_isleaf()
624
625
626 :ALL :CONSTANTS, :FUNCTIONS
627
628
629 Error values
630 The functions in this module return undef or an empty list when an
631 underlying library function fails. The $! is set to provide more infor‐
632 mation values for the error. The following error codes are possible:
633
634 EINVAL The value supplied is not valid.
635
636
637 ENOMEM There was not enough system memory to complete an operation.
638
639
640 EPERM The effective user of the calling process does not have
641 appropriate privileges, and its real or effective user ID
642 does not match the real or effective user ID of one of the
643 threads.
644
645
646 ESRCH The specified process or thread was not found.
647
648
649 Difference in the API versions
650 The liblgrp(3LIB) library is versioned. The exact version that was used
651 to compile a module is available through the lgrp_version() function.
652
653
654 Version 2 of the lgrp_user API introduced the following constants and
655 functions not present in version 1:
656 LGRP_RSRC_CPU constant
657 LGRP_RSRC_MEM constant
658 LGRP_CONTENT_ALL constant
659 LGRP_LAT_CPU_TO_MEM constant
660 lgrp_resources() function
661 lgrp_latency_cookie() function
662
663
664 The LGRP_RSRC_CPU and LGRP_RSRC_MEM constants are not defined for ver‐
665 sion 1. The lgrp_resources() function is defined for version 1 but
666 always returns an empty list. The lgrp_latency_cookie() function is an
667 alias for lgrp_latency() for version 1.
668
670 See attributes(5) for descriptions of the following attributes:
671
672
673
674
675 ┌─────────────────────────────┬─────────────────────────────┐
676 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
677 ├─────────────────────────────┼─────────────────────────────┤
678 │Availability │SUNWpl5u │
679 ├─────────────────────────────┼─────────────────────────────┤
680 │Interface Stability │Unstable │
681 └─────────────────────────────┴─────────────────────────────┘
682
684 lgrp_affinity_get(3LGRP), lgrp_affinity_set(3LGRP), lgrp_chil‐
685 dren(3LGRP), lgrp_cookie_stale(3LGRP), lgrp_cpus(3LGRP),
686 lgrp_fini(3LGRP), lgrp_home(3LGRP), lgrp_init(3LGRP),
687 lgrp_latency(3LGRP), lgrp_latency_cookie(3LGRP), lgrp_mem_size(3LGRP),
688 lgrp_nlgrps(3LGRP), lgrp_parents(3LGRP), lgrp_resources(3LGRP),
689 lgrp_root(3LGRP), lgrp_version(3LGRP), lgrp_view(3LGRP), liblgrp(3LIB),
690 attributes(5)
691
692
693
694SunOS 5.11 30 Aug 2006 Lgrp(3PERL)