add comments for utility, the USER_HZ for /proc/stat

@@ -283,6 +283,17 @@ bool get_proc_self_stat(SrsProcSelfStat& r)
 
 
 void srs_update_proc_stat()
 void srs_update_proc_stat()
 {
 {
+    // always assert the USER_HZ is 1/100ths
+    // @see: http://stackoverflow.com/questions/7298646/calculating-user-nice-sys-idle-iowait-irq-and-sirq-from-proc-stat/7298711
+    static bool user_hz_assert = false;
+    if (!user_hz_assert) {
+        user_hz_assert = true;
+        
+        int USER_HZ = sysconf(_SC_CLK_TCK);
+        srs_trace("USER_HZ=%d", USER_HZ);
+        srs_assert(USER_HZ == 100);
+    }
+    
     // system cpu stat
     // system cpu stat
     if (true) {
     if (true) {
         SrsProcSystemStat r;
         SrsProcSystemStat r;

@@ -49,6 +49,7 @@ extern int srs_socket_connect(std::string server, int port, int64_t timeout, st_
 */
 */
 extern int srs_get_log_level(std::string level);
 extern int srs_get_log_level(std::string level);
 
 
+// current process resouce usage.
 // @see: man getrusage
 // @see: man getrusage
 class SrsRusage
 class SrsRusage
 {
 {
@@ -68,6 +69,7 @@ extern SrsRusage* srs_get_system_rusage();
 // the deamon st-thread will update it.
 // the deamon st-thread will update it.
 extern void srs_update_system_rusage();
 extern void srs_update_system_rusage();
 
 
+// to stat the process info.
 // @see: man 5 proc, /proc/[pid]/stat
 // @see: man 5 proc, /proc/[pid]/stat
 class SrsProcSelfStat
 class SrsProcSelfStat
 {
 {
@@ -220,7 +222,23 @@ public:
     SrsProcSelfStat();
     SrsProcSelfStat();
 };
 };
 
 
+// to stat the cpu time.
 // @see: man 5 proc, /proc/stat
 // @see: man 5 proc, /proc/stat
+/**
+* about the cpu time, @see: http://stackoverflow.com/questions/16011677/calculating-cpu-usage-using-proc-files
+* for example, for ossrs.net, a single cpu machine:
+*       [winlin@SRS ~]$ cat /proc/uptime && cat /proc/stat
+*           5275153.01 4699624.99
+*           cpu  43506750 973 8545744 466133337 4149365 190852 804666 0 0
+* where the uptime is 5275153.01s
+* generally, USER_HZ sysconf(_SC_CLK_TCK)=100, which means the unit of /proc/stat is "1/100ths seconds"
+*       that is, USER_HZ=1/100 seconds
+* cpu total = 43506750+973+8545744+466133337+4149365+190852+804666+0+0 (USER_HZ)
+*           = 523331687 (USER_HZ)
+*           = 523331687 * 1/100 (seconds)
+*           = 5233316.87 seconds
+* the cpu total seconds almost the uptime, the delta is more precise.
+*/
 class SrsProcSystemStat
 class SrsProcSystemStat
 {
 {
 public:
 public:
@@ -234,7 +252,8 @@ public:
     // always be cpu
     // always be cpu
     char label[32];
     char label[32];
     
     
-    //The amount of time, measured in units  of  USER_HZ  (1/100ths  of  a  second  on  most  architectures,  use
+    // The amount of time, measured in units  of  USER_HZ  
+    // (1/100ths  of  a  second  on  most  architectures,  use
     // sysconf(_SC_CLK_TCK)  to  obtain  the  right value)
     // sysconf(_SC_CLK_TCK)  to  obtain  the  right value)
     //
     //
     // the system spent in user mode, 
     // the system spent in user mode, 
@@ -275,6 +294,7 @@ extern SrsProcSystemStat* srs_get_system_proc_stat();
 // the deamon st-thread will update it.
 // the deamon st-thread will update it.
 extern void srs_update_proc_stat();
 extern void srs_update_proc_stat();
 
 
+// stat system memory info
 // @see: cat /proc/meminfo 
 // @see: cat /proc/meminfo 
 class SrsMemInfo
 class SrsMemInfo
 {
 {
@@ -312,6 +332,7 @@ extern SrsMemInfo* srs_get_meminfo();
 // the deamon st-thread will update it.
 // the deamon st-thread will update it.
 extern void srs_update_meminfo();
 extern void srs_update_meminfo();
 
 
+// system cpu hardware info.
 // @see: cat /proc/cpuinfo 
 // @see: cat /proc/cpuinfo 
 class SrsCpuInfo
 class SrsCpuInfo
 {
 {
@@ -330,7 +351,7 @@ public:
 // get system cpu info, use cache to avoid performance problem.
 // get system cpu info, use cache to avoid performance problem.
 extern SrsCpuInfo* srs_get_cpuinfo();
 extern SrsCpuInfo* srs_get_cpuinfo();
 
 
-// platform(os, srs) summary
+// platform(os, srs) uptime/load summary
 class SrsPlatformInfo
 class SrsPlatformInfo
 {
 {
 public:
 public:
@@ -341,7 +362,11 @@ public:
     int64_t srs_startup_time;
     int64_t srs_startup_time;
     
     
     // @see: cat /proc/uptime
     // @see: cat /proc/uptime
+    // system startup time in seconds.
     double os_uptime;
     double os_uptime;
+    // system all cpu idle time in seconds.
+    // @remark to cal the cpu ustime percent:
+    //      os_ilde_time % (os_uptime * SrsCpuInfo.nb_processors_online)
     double os_ilde_time;
     double os_ilde_time;
     
     
     // @see: cat /proc/loadavg
     // @see: cat /proc/loadavg
@@ -446,6 +471,7 @@ std::string srs_get_local_ip(int fd);
 // where peer ip is the client public ip which connected to server.
 // where peer ip is the client public ip which connected to server.
 std::string srs_get_peer_ip(int fd);
 std::string srs_get_peer_ip(int fd);
 
 
+// dump summaries for /api/v1/summaries.
 void srs_api_dump_summaries(std::stringstream& ss);
 void srs_api_dump_summaries(std::stringstream& ss);
 
 
 #endif
 #endif