Add the speculative.stp tapset

The speculative.stp tapset allow one to speculative add things to
output buffers and then later commit or discard the information in the
buffers.  Four functions in the tapset:

speculation() - function to give an id for speculative buffer
speculate() - add output to a speculative buffer
discard() - remove output for a speculative buffer
commit() - output data for a speculative buffer

diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
index 685c733c35d91bc3e954dd475bfcb8979dc290f2..dd78a4eb2b9c457fe807eda74c502b8372c279bd 100644 (file)
--- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl
+++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl
@@ -389,4 +389,14 @@
 !Itapset/nfsd.stp
 !Itapset/nfsderrno.stp
   </chapter>
+
+  <chapter id="speculation.stp">
+    <title>Speculation</title>
+    <para>
+      This family of functions provides the ability to speculative record
+      information and then at a later point in the SystemTap script either
+      commit the information or discard it.
+    </para>
+!Itapset/speculative.stp
+  </chapter>
 </book>

diff --git a/tapset/speculative.stp b/tapset/speculative.stp
new file mode 100644 (file)
index 0000000..4338672
--- /dev/null
+++ b/tapset/speculative.stp
@@ -0,0 +1,80 @@
+// Speculative tapset
+// Copyright (C) 2011 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.
+
+global _spec_id
+global _spec_counter
+global _spec_buff
+global _spec_discard
+
+/**
+ * sfunction speculation - Allocate a new id for speculative output
+ *
+ * The speculation() function is called when a new speculation buffer is needed.
+ * It returns an id for the speculative output.
+ * There can be multiple threads being speculated on concurrently.
+ * This id is used by other speculation fuctions to keep the threads
+ * separate.
+ */
+function speculation:long ()
+{
+       _spec_id += 1
+       return _spec_id
+}
+
+
+/**
+ * sfunction speculate - Store a string for possible output later
+ * @id: buffer id to store the information in
+ * @output: string to write out when commit occurs
+ *
+ * Add a string to the speculaive buffer for id.
+ */
+function speculate (id:long, output:string)
+{
+       _spec_counter[id] += 1
+       _spec_buff[id, _spec_counter[id]] = output
+}
+
+
+function _spec_erase (id:long) {
+       foreach([i, counter] in _spec_discard)
+               delete _spec_buff[i, counter]
+       delete _spec_discard
+}
+
+
+/**
+ * sfunction discard - Discard all output related to a speculation buffer
+ * @id: of the buffer to store the information in
+ *
+ */
+function discard (id:long)
+{
+       foreach([i, counter] in _spec_buff)
+               if (i==id) _spec_discard[i, counter] = 1
+       _spec_erase (id)
+}
+
+
+/**
+ * sfunction commit - Write out all output related to a speculation buffer
+ * @id: of the buffer to store the information in
+ *
+ * Output all the output for @id in the order that it was entered into
+ * the speculative buffer by speculative().
+ */
+function commit (id:long)
+{
+       foreach([i, counter+] in _spec_buff) {
+               if (i==id) {
+                       printf("%s", _spec_buff[i, counter])
+                       _spec_discard[i, counter] = 1
+               }
+       }
+       _spec_erase (id)
+}