Add task_time tapset, functions to query time resource usage of current task.

* tapset/task_time.stp: New tapset.
* testsuite/buildok/task_test.stp: Add new task_time functions.
* doc/SystemTap_Tapset_Reference/tapsets.tmpl: Add new section on
  Task Time Tapset. Include tapset/task_time.stp.

3 files changed, 119 insertions, 0 deletions

diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
index 705cd3b5..c8c5ed72 100644
--- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl
+++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
@@ -146,6 +146,16 @@
 !Itapset/proc_mem.stp
   </chapter>
 
+  <chapter id="task_time_stp">
+    <title>Task Time Tapset</title>
+    <para>
+      This tapset defines utility functions to query time related
+      properties of the current tasks, translate those in miliseconds
+      and human readable strings.
+    </para>
+!Itapset/task_time.stp
+  </chapter>
+
   <chapter id="iosched.stp">
     <title>IO Scheduler Tapset</title>
     <para>
diff --git a/tapset/task_time.stp b/tapset/task_time.stp
new file mode 100644
index 00000000..55b7934c
--- /dev/null
+++ b/tapset/task_time.stp
@@ -0,0 +1,101 @@
+// Task time query and utility functions.
+// Copyright (C) 2009 Red Hat Inc.
+//
+// This file is part of systemtap, and is free software.  You can
+// redistribute it and/or modify it under the terms of the GNU General
+// Public License (GPL); either version 2, or (at your option) any
+// later version.
+
+// <tapsetdescription>
+// Task time query and utility functions provide information about
+// the time resource usage of the current task. These functions provide
+// information about the user time and system time of the current
+// task. And provide utility functions to turn the reported times
+// into miliseconds and create human readable string representations
+// of task time used. The reported times are approximates and should
+// be used for "coarse grained" measurements only. The reported user
+// and system time are only for the current task, not for the process
+// as a whole nor of any time spend by children of the current task.
+// </tapsetdescription>
+
+%{
+#include <asm/cputime.h>
+#include <linux/time.h>
+%}
+
+/**
+ * sfunction task_utime - User time of the current task.
+ *
+ * Description: Returns the user time of the current task in cputime.
+ * Does not include any time used by other tasks in this process, nor
+ * does it include any time of the children of this task.
+ */
+function task_utime:long ()
+%{ /* pure */ /* unprivileged */
+  THIS->__retvalue = current->utime;
+%}
+
+/**
+ * sfunction task_stime - System time of the current task.
+ *
+ * Description: Returns the system time of the current task in cputime.
+ * Does not include any time used by other tasks in this process, nor
+ * does it include any time of the children of this task.
+ */
+function task_stime:long ()
+%{ /* pure */ /* unprivileged */
+  THIS->__retvalue = current->stime;
+%}
+
+/**
+ * sfunction cputime_to_msecs - Translates the given cputime into milliseconds.
+ * @cputime: Time to convert to milliseconds.
+ */
+function cputime_to_msecs:long (cputime:long)
+%{ /* pure */ /* unprivileged */
+  THIS->__retvalue = cputime_to_msecs (THIS->cputime);
+%}
+
+/**
+ * sfunction msecs_to_string - Human readable string for given milliseconds.
+ * @msecs: Number of milliseconds to translate.
+ *
+ * Description: Returns a string representing the number of
+ * milliseconds as a human readable string consisting of "XmY.ZZZs",
+ * where X is the number of minutes, Y is the number of seconds and
+ * ZZZ is the number of milliseconds.
+ */
+function msecs_to_string:string (msecs:long)
+{
+  ms = msecs % 1000;
+  secs = msecs / 1000;
+  mins = secs / 60;
+  secs = secs % 60;
+  return sprintf("%dm%d.%.3ds", mins, secs, ms);
+}
+
+/**
+ * sfunction cputime_to_string - Human readable string for given cputime.
+ * @cputime: Time to translate.
+ *
+ * Description: Equivalent to calling:
+ * msec_to_string (cputime_to_msecs (cputime).
+ */
+function cputime_to_string:string (cputime:long)
+{
+  return msecs_to_string (cputime_to_msecs (cputime));
+}
+
+/**
+ * sfunction task_time_string - Human readable string of task time usage.
+ *
+ * Description: Returns a human readable string showing the user and
+ * system time the current task has used up to now.  For example
+ * "usr: 0m12.908s, sys: 1m6.851s".
+ */
+function task_time_string:string ()
+{
+  return sprintf ("usr: %s, sys: %s",
+                  cputime_to_string (task_utime()),
+                  cputime_to_string (task_stime()));
+}
diff --git a/testsuite/buildok/task_test.stp b/testsuite/buildok/task_test.stp
index 792f96ea..e391377f 100755
--- a/testsuite/buildok/task_test.stp
+++ b/testsuite/buildok/task_test.stp
@@ -18,5 +18,13 @@ probe begin {
   log(sprint(task_max_file_handles(c)))
   log(sprint(pid2task(pid())))
   log(sprint(pid2execname(pid())))
+
+  // task_time.stp
+  log(task_time_string())
+  log(cputime_to_string(0))
+  log(msecs_to_string(0))
+  log(sprint(cputime_to_msecs(0)))
+  log(sprint(task_stime()))
+  log(sprint(task_utime()))
   exit()
 }