usr/src/man/man3c_db/td_ta_enable_stats.3c_db

   1 '\" te
   2 .\"  Copyright (c) 1996 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 TD_TA_ENABLE_STATS 3C_DB "Oct 20, 1998"
   7 .SH NAME
   8 td_ta_enable_stats, td_ta_reset_stats, td_ta_get_stats \- collect target
   9 process statistics for libc_db
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
  14 #include <proc_service.h>
  15 #include <thread_db.h>
  16
  17 \fBtd_err_e\fR \fBtd_ta_enable_stats\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBint\fR\fI on_off\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBtd_err_e_stats\fR \fBtd_ta_reset\fR(\fBconst td_thragent_t *\fR\fIta_p\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBtd_err_e\fR \fBtd_ta_get_stats\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBtd_ta_stats_t *\fR\fItstats\fR);
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The controlling process can request the collection of certain statistics about
  34 a target process.  Statistics gathering is disabled by default. Each target
  35 process has a \fBtd_ta_stats_t\fR structure that contains current values when
  36 statistic gathering is enabled.
  37 .sp
  38 .LP
  39 The \fBtd_ta_enable_stats()\fR function turns statistics gathering on or off
  40 for the process identified by \fIta_p\fR, depending on whether or not
  41 \fIon_off\fR is non-zero. When statistics gathering is turned on, all
  42 statistics are implicitly reset as though \fBtd_ta_reset_stats()\fR had been
  43 called.  Statistics are not reset when statistics gathering  is turned off.
  44 Except for \fBnthreads\fR \fBand\fR \fBr_concurrency\fR, the values do not
  45 change further, but they remain available for inspection by way of
  46 \fBtd_ta_get_stats()\fR.
  47 .sp
  48 .LP
  49 The \fBtd_ta_reset_stats()\fR function resets all counters in the
  50 \fBtd_ta_stats_t\fR structure to zero for the target process.
  51 .sp
  52 .LP
  53 The \fBtd_ta_get_stats()\fR function returns the structure for the process in
  54 \fItstats\fR.
  55 .sp
  56 .LP
  57 The \fBtd_ta_stats_t\fR structure is defined in <\fBthread_db.h\fR> and
  58 contains the following members:
  59 .sp
  60 .in +2
  61 .nf
  62 typedef struct {
  63    int nthreads;            /* total number of threads in use */
  64    int r_concurrency;       /* requested concurrency level */
  65    int nrunnable_num;       /* numerator of avg runnable threads */
  66    int nrunnable_den;       /* denominator of avg runnable threads */
  67    int a_concurrency_num;   /* numerator, avg achieved concurrency */
  68    int a_concurrency_den;   /* denominator, avg achieved concurrency */
  69    int nlwps_num;           /* numerator, avg number of LWPs in use */
  70    int nlwps_den;           /* denominator, avg number of LWPs in use */
  71    int nidle_num;           /* numerator, avg number of idling LWPs */
  72    int nidle_den;           /* denominator, avg number of idling LWPs */
  73 } td_ta_stats_t;\fI\fR
  74 .fi
  75 .in -2
  76
  77 .sp
  78 .LP
  79 The \fBnthreads\fR member is the number of threads that are currently part of
  80 the target process.  The \fBr_concurrency\fR member is the current requested
  81 concurrency level, such as would be returned by \fBthr_setconcurrency\fR(3C).
  82 The remaining members are averages over time, each expressed as  a fraction
  83 with an integral numerator and denominator. The \fBnrunnable_num\fR and
  84 \fBnrunnable_den\fR members represent the average number of runnable threads.
  85 The \fBa_concurrency_num\fR and \fBa_concurrency_den\fR members represent the
  86 average achieved concurrency, the number of actually running threads.  The
  87 \fBa_concurrency_num\fR and \fBa_concurrency_den\fR members are less than or
  88 equal to \fBnrunnable_num\fR and \fBnrunnable_den\fR, respectively. The
  89 \fBnlwps_num\fR and \fBnlwps_den\fR members represent the average number of
  90 lightweight processes  (\fBLWP\fRs) participating in this process. They must be
  91 greater than or equal to \fBa_concurrency_num\fR and \fBa_concurrency_den\fR,
  92 respectively, since every running thread is assigned to an  \fBLWP\fR, but
  93 there can at times be additional idling \fBLWP\fRs with no thread assigned to
  94 them. The \fBnidle_num\fR and \fBnidle_den\fR members represent the average
  95 number of idle \fBLWP\fRs.
  96 .SH RETURN VALUES
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBTD_OK\fR \fR
 101 .ad
 102 .RS 13n
 103 The call completed successfully.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBTD_BADTA\fR \fR
 110 .ad
 111 .RS 13n
 112 An invalid internal process handle was passed in.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBTD_DBERR\fR \fR
 119 .ad
 120 .RS 13n
 121 A call to one of the imported interface routines failed.
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBTD_ERR\fR \fR
 128 .ad
 129 .RS 13n
 130 Something else went wrong.
 131 .RE
 132
 133 .SH ATTRIBUTES
 134 .sp
 135 .LP
 136 See \fBattributes\fR(5) for description of the following attributes:
 137 .sp
 138
 139 .sp
 140 .TS
 141 box;
 142 c | c
 143 l | l .
 144 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 145 _
 146 MT Level        Safe
 147 .TE
 148
 149 .SH SEE ALSO
 150 .sp
 151 .LP
 152 \fBlibc_db\fR(3LIB), \fBthr_getconcurrency\fR(3C), \fBattributes\fR(5)