Mu - subx/003trace.cc

From 25ad969f7582d9253f5329812aed5ed5784d8ec8 Mon Sep 17 00:00:00 2001 From: "Kartik K. Agaram" Date: Thu, 12 Oct 2017 23:43:09 -0700 Subject: 4052 --- html/subx/003trace.cc.html | 463 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 463 insertions(+) create mode 100644 html/subx/003trace.cc.html (limited to 'html/subx/003trace.cc.html') diff --git a/html/subx/003trace.cc.html b/html/subx/003trace.cc.html new file mode 100644 index 00000000..9fca7be6 --- /dev/null +++ b/html/subx/003trace.cc.html @@ -0,0 +1,463 @@ + + + + +Mu - subx/003trace.cc + + + + + + + + + + +
+  1 //: The goal of layers is to make programs more easy to understand and more
+  2 //: malleable, easy to rewrite in radical ways without accidentally breaking
+  3 //: some corner case. Tests further both goals. They help understandability by
+  4 //: letting one make small changes and get feedback. What if I wrote this line
+  5 //: like so? What if I removed this function call, is it really necessary?
+  6 //: Just try it, see if the tests pass. Want to explore rewriting this bit in
+  7 //: this way? Tests put many refactorings on a firmer footing.
+  8 //:
+  9 //: But the usual way we write tests seems incomplete. Refactorings tend to
+ 10 //: work in the small, but don't help with changes to function boundaries. If
+ 11 //: you want to extract a new function you have to manually test-drive it to
+ 12 //: create tests for it. If you want to inline a function its tests are no
+ 13 //: longer valid. In both cases you end up having to reorganize code as well as
+ 14 //: tests, an error-prone activity.
+ 15 //:
+ 16 //: In response, this layer introduces the notion of *domain-driven* testing.
+ 17 //: We focus on the domain of inputs the whole program needs to handle rather
+ 18 //: than the correctness of individual functions. All tests invoke the program
+ 19 //: in a single way: by calling run() with some input. As the program operates
+ 20 //: on the input, it traces out a list of _facts_ deduced about the domain:
+ 21 //:   trace("label") << "fact 1: " << val;
+ 22 //:
+ 23 //: Tests can now check these facts:
+ 24 //:   :(scenario foo)
+ 25 //:   34  # call run() with this input
+ 26 //:   +label: fact 1: 34  # 'run' should have deduced this fact
+ 27 //:   -label: fact 1: 35  # the trace should not contain such a fact
+ 28 //:
+ 29 //: Since we never call anything but the run() function directly, we never have
+ 30 //: to rewrite the tests when we reorganize the internals of the program. We
+ 31 //: just have to make sure our rewrite deduces the same facts about the domain,
+ 32 //: and that's something we're going to have to do anyway.
+ 33 //:
+ 34 //: To avoid the combinatorial explosion of integration tests, each layer
+ 35 //: mainly logs facts to the trace with a common *label*. All tests in a layer
+ 36 //: tend to check facts with this label. Validating the facts logged with a
+ 37 //: specific label is like calling functions of that layer directly.
+ 38 //:
+ 39 //: To build robust tests, trace facts about your domain rather than details of
+ 40 //: how you computed them.
+ 41 //:
+ 42 //: More details: http://akkartik.name/blog/tracing-tests
+ 43 //:
+ 44 //: ---
+ 45 //:
+ 46 //: Between layers and domain-driven testing, programming starts to look like a
+ 47 //: fundamentally different activity. Instead of a) superficial, b) local rules
+ 48 //: on c) code [like say http://blog.bbv.ch/2013/06/05/clean-code-cheat-sheet],
+ 49 //: we allow programmers to engage with the a) deep, b) global structure of the
+ 50 //: c) domain. If you can systematically track discontinuities in the domain,
+ 51 //: you don't care if the code used gotos as long as it passed the tests. If
+ 52 //: tests become more robust to run it becomes easier to try out radically
+ 53 //: different implementations for the same program. If code is super-easy to
+ 54 //: rewrite, it becomes less important what indentation style it uses, or that
+ 55 //: the objects are appropriately encapsulated, or that the functions are
+ 56 //: referentially transparent.
+ 57 //:
+ 58 //: Instead of plumbing, programming becomes building and gradually refining a
+ 59 //: map of the environment the program must operate under. Whether a program is
+ 60 //: 'correct' at a given point in time is a red herring; what matters is
+ 61 //: avoiding regression by monotonically nailing down the more 'eventful' parts
+ 62 //: of the terrain. It helps readers new and old, and rewards curiosity, to
+ 63 //: organize large programs in self-similar hierarchies of example scenarios
+ 64 //: colocated with the code that makes them work.
+ 65 //:
+ 66 //:   "Programming properly should be regarded as an activity by which
+ 67 //:   programmers form a mental model, rather than as production of a program."
+ 68 //:   -- Peter Naur (http://alistair.cockburn.us/ASD+book+extract%3A+%22Naur,+Ehn,+Musashi%22)
+ 69 
+ 70 :(before "End Types")
+ 71 struct trace_line {
+ 72   int depth;  // optional field just to help browse traces later
+ 73   string label;
+ 74   string contents;
+ 75   trace_line(string l, string c) :depth(0), label(l), contents(c) {}
+ 76   trace_line(int d, string l, string c) :depth(d), label(l), contents(c) {}
+ 77 };
+ 78 
+ 79 :(before "End Globals")
+ 80 bool Hide_errors = false;
+ 81 bool Dump_trace = false;
+ 82 string Dump_label = "";
+ 83 :(before "End Reset")
+ 84 Hide_errors = false;
+ 85 Dump_trace = false;
+ 86 Dump_label = "";
+ 87 
+ 88 :(before "End Types")
+ 89 // Pre-define some global constants that trace_stream needs to know about.
+ 90 // Since they're in the Types section, they'll be included in any cleaved
+ 91 // compilation units. So no extern linkage.
+ 92 const int Max_depth = 9999;
+ 93 const int Error_depth = 0;  // definitely always print errors
+ 94 
+ 95 struct trace_stream {
+ 96   vector<trace_line> past_lines;
+ 97   // accumulator for current line
+ 98   ostringstream* curr_stream;
+ 99   string curr_label;
+100   int curr_depth;
+101   int callstack_depth;
+102   int collect_depth;
+103   ofstream null_stream;  // never opens a file, so writes silently fail
+104   trace_stream() :curr_stream(NULL), curr_depth(Max_depth), callstack_depth(0), collect_depth(Max_depth) {}
+105   ~trace_stream() { if (curr_stream) delete curr_stream; }
+106 
+107   ostream& stream(string label) {
+108   ¦ return stream(Max_depth, label);
+109   }
+110 
+111   ostream& stream(int depth, string label) {
+112   ¦ if (depth > collect_depth) return null_stream;
+113   ¦ curr_stream = new ostringstream;
+114   ¦ curr_label = label;
+115   ¦ curr_depth = depth;
+116   ¦ return *curr_stream;
+117   }
+118 
+119   // be sure to call this before messing with curr_stream or curr_label
+120   void newline();
+121   // useful for debugging
+122   string readable_contents(string label);  // empty label = show everything
+123 };
+124 
+125 :(code)
+126 void trace_stream::newline() {
+127   if (!curr_stream) return;
+128   string curr_contents = curr_stream->str();
+129   if (!curr_contents.empty()) {
+130   ¦ past_lines.push_back(trace_line(curr_depth, trim(curr_label), curr_contents));  // preserve indent in contents
+131   ¦ if ((!Hide_errors && curr_label == "error")
+132   ¦ ¦ ¦ || Dump_trace
+133   ¦ ¦ ¦ || (!Dump_label.empty() && curr_label == Dump_label))
+134   ¦ ¦ cerr << curr_label << ": " << curr_contents << '\n';
+135   }
+136   delete curr_stream;
+137   curr_stream = NULL;
+138   curr_label.clear();
+139   curr_depth = Max_depth;
+140 }
+141 
+142 string trace_stream::readable_contents(string label) {
+143   ostringstream output;
+144   label = trim(label);
+145   for (vector<trace_line>::iterator p = past_lines.begin();  p != past_lines.end();  ++p)
+146   ¦ if (label.empty() || label == p->label) {
+147   ¦ ¦ output << std::setw(4) << p->depth << ' ' << p->label << ": " << p->contents << '\n';
+148   ¦ }
+149   return output.str();
+150 }
+151 
+152 :(before "End Globals")
+153 trace_stream* Trace_stream = NULL;
+154 int Trace_errors = 0;  // used only when Trace_stream is NULL
+155 
+156 :(before "End Includes")
+157 #define CLEAR_TRACE  delete Trace_stream, Trace_stream = new trace_stream;
+158 
+159 // Top-level helper. IMPORTANT: can't nest
+160 #define trace(...)  !Trace_stream ? cerr /*print nothing*/ : Trace_stream->stream(__VA_ARGS__)
+161 
+162 // Just for debugging; 'git log' should never show any calls to 'dbg'.
+163 #define dbg trace(0, "a")
+164 #define DUMP(label)  if (Trace_stream) cerr << Trace_stream->readable_contents(label);
+165 
+166 // Errors are a special layer.
+167 #define raise  (!Trace_stream ? (++Trace_errors,cerr) /*do print*/ : Trace_stream->stream(Error_depth, "error"))
+168 // If we aren't yet sure how to deal with some corner case, use assert_for_now
+169 // to indicate that it isn't an inviolable invariant.
+170 #define assert_for_now assert
+171 
+172 // Inside tests, fail any tests that displayed (unexpected) errors.
+173 // Expected errors in tests should always be hidden and silently checked for.
+174 :(before "End Test Teardown")
+175 if (Passed && !Hide_errors && trace_contains_errors()) {
+176   Passed = false;
+177 }
+178 :(code)
+179 bool trace_contains_errors() {
+180   return Trace_errors > 0 || trace_count("error") > 0;
+181 }
+182 
+183 :(before "End Types")
+184 struct end {};
+185 :(code)
+186 ostream& operator<<(ostream& os, unused end) {
+187   if (Trace_stream) Trace_stream->newline();
+188   return os;
+189 }
+190 
+191 :(before "End Globals")
+192 bool Save_trace = false;
+193 
+194 // Trace_stream is a resource, lease_tracer uses RAII to manage it.
+195 :(before "End Types")
+196 struct lease_tracer {
+197   lease_tracer();
+198   ~lease_tracer();
+199 };
+200 :(code)
+201 lease_tracer::lease_tracer() { Trace_stream = new trace_stream; }
+202 lease_tracer::~lease_tracer() {
+203   if (!Trace_stream) return;  // in case tests close Trace_stream
+204   if (Save_trace) {
+205   ¦ ofstream fout("last_trace");
+206   ¦ fout << Trace_stream->readable_contents("");
+207   ¦ fout.close();
+208   }
+209   delete Trace_stream, Trace_stream = NULL;
+210 }
+211 :(before "End Includes")
+212 #define START_TRACING_UNTIL_END_OF_SCOPE  lease_tracer leased_tracer;
+213 :(before "End Test Setup")
+214 START_TRACING_UNTIL_END_OF_SCOPE
+215 
+216 :(before "End Includes")
+217 #define CHECK_TRACE_CONTENTS(...)  check_trace_contents(__FUNCTION__, __FILE__, __LINE__, __VA_ARGS__)
+218 
+219 #define CHECK_TRACE_CONTAINS_ERRORS()  CHECK(trace_contains_errors())
+220 #define CHECK_TRACE_DOESNT_CONTAIN_ERRORS() \
+221   if (Passed && trace_contains_errors()) { \
+222   ¦ cerr << "\nF - " << __FUNCTION__ << "(" << __FILE__ << ":" << __LINE__ << "): unexpected errors\n"; \
+223   ¦ DUMP("error"); \
+224   ¦ Passed = false; \
+225   ¦ return; \
+226   }
+227 
+228 #define CHECK_TRACE_COUNT(label, count) \
+229   if (Passed && trace_count(label) != (count)) { \
+230   ¦ cerr << "\nF - " << __FUNCTION__ << "(" << __FILE__ << ":" << __LINE__ << "): trace_count of " << label << " should be " << count << '\n'; \
+231   ¦ cerr << "  got " << trace_count(label) << '\n';  /* multiple eval */ \
+232   ¦ DUMP(label); \
+233   ¦ Passed = false; \
+234   ¦ return;  /* Currently we stop at the very first failure. */ \
+235   }
+236 
+237 #define CHECK_TRACE_DOESNT_CONTAIN(...)  CHECK(trace_doesnt_contain(__VA_ARGS__))
+238 
+239 :(code)
+240 bool check_trace_contents(string FUNCTION, string FILE, int LINE, string expected) {
+241   if (!Passed) return false;
+242   if (!Trace_stream) return false;
+243   vector<string> expected_lines = split(expected, "^D");
+244   int curr_expected_line = 0;
+245   while (curr_expected_line < SIZE(expected_lines) && expected_lines.at(curr_expected_line).empty())
+246   ¦ ++curr_expected_line;
+247   if (curr_expected_line == SIZE(expected_lines)) return true;
+248   string label, contents;
+249   split_label_contents(expected_lines.at(curr_expected_line), &label, &contents);
+250   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
+251   ¦ if (label != p->label) continue;
+252   ¦ if (contents != trim(p->contents)) continue;
+253   ¦ ++curr_expected_line;
+254   ¦ while (curr_expected_line < SIZE(expected_lines) && expected_lines.at(curr_expected_line).empty())
+255   ¦ ¦ ++curr_expected_line;
+256   ¦ if (curr_expected_line == SIZE(expected_lines)) return true;
+257   ¦ split_label_contents(expected_lines.at(curr_expected_line), &label, &contents);
+258   }
+259 
+260   if (line_exists_anywhere(label, contents)) {
+261   ¦ cerr << "\nF - " << FUNCTION << "(" << FILE << ":" << LINE << "): line [" << label << ": " << contents << "] out of order in trace:\n";
+262   ¦ DUMP("");
+263   }
+264   else {
+265   ¦ cerr << "\nF - " << FUNCTION << "(" << FILE << ":" << LINE << "): missing [" << contents << "] in trace:\n";
+266   ¦ DUMP(label);
+267   }
+268   Passed = false;
+269   return false;
+270 }
+271 
+272 void split_label_contents(const string& s, string* label, string* contents) {
+273   static const string delim(": ");
+274   size_t pos = s.find(delim);
+275   if (pos == string::npos) {
+276   ¦ *label = "";
+277   ¦ *contents = trim(s);
+278   }
+279   else {
+280   ¦ *label = trim(s.substr(0, pos));
+281   ¦ *contents = trim(s.substr(pos+SIZE(delim)));
+282   }
+283 }
+284 
+285 bool line_exists_anywhere(const string& label, const string& contents) {
+286   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
+287   ¦ if (label != p->label) continue;
+288   ¦ if (contents == trim(p->contents)) return true;
+289   }
+290   return false;
+291 }
+292 
+293 int trace_count(string label) {
+294   return trace_count(label, "");
+295 }
+296 
+297 int trace_count(string label, string line) {
+298   if (!Trace_stream) return 0;
+299   long result = 0;
+300   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
+301   ¦ if (label == p->label) {
+302   ¦ ¦ if (line == "" || trim(line) == trim(p->contents))
+303   ¦ ¦ ¦ ++result;
+304   ¦ }
+305   }
+306   return result;
+307 }
+308 
+309 int trace_count_prefix(string label, string prefix) {
+310   if (!Trace_stream) return 0;
+311   long result = 0;
+312   for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin();  p != Trace_stream->past_lines.end();  ++p) {
+313   ¦ if (label == p->label) {
+314   ¦ ¦ if (starts_with(trim(p->contents), trim(prefix)))
+315   ¦ ¦ ¦ ++result;
+316   ¦ }
+317   }
+318   return result;
+319 }
+320 
+321 bool trace_doesnt_contain(string label, string line) {
+322   return trace_count(label, line) == 0;
+323 }
+324 
+325 bool trace_doesnt_contain(string expected) {
+326   vector<string> tmp = split_first(expected, ": ");
+327   return trace_doesnt_contain(tmp.at(0), tmp.at(1));
+328 }
+329 
+330 vector<string> split(string s, string delim) {
+331   vector<string> result;
+332   size_t begin=0, end=s.find(delim);
+333   while (true) {
+334   ¦ if (end == string::npos) {
+335   ¦ ¦ result.push_back(string(s, begin, string::npos));
+336   ¦ ¦ break;
+337   ¦ }
+338   ¦ result.push_back(string(s, begin, end-begin));
+339   ¦ begin = end+SIZE(delim);
+340   ¦ end = s.find(delim, begin);
+341   }
+342   return result;
+343 }
+344 
+345 vector<string> split_first(string s, string delim) {
+346   vector<string> result;
+347   size_t end=s.find(delim);
+348   result.push_back(string(s, 0, end));
+349   if (end != string::npos)
+350   ¦ result.push_back(string(s, end+SIZE(delim), string::npos));
+351   return result;
+352 }
+353 
+354 string trim(const string& s) {
+355   string::const_iterator first = s.begin();
+356   while (first != s.end() && isspace(*first))
+357   ¦ ++first;
+358   if (first == s.end()) return "";
+359 
+360   string::const_iterator last = --s.end();
+361   while (last != s.begin() && isspace(*last))
+362   ¦ --last;
+363   ++last;
+364   return string(first, last);
+365 }
+366 
+367 :(before "End Includes")
+368 #include <vector>
+369 using std::vector;
+370 #include <list>
+371 using std::list;
+372 #include <map>
+373 using std::map;
+374 #include <set>
+375 using std::set;
+376 #include <algorithm>
+377 
+378 #include <sstream>
+379 using std::istringstream;
+380 using std::ostringstream;
+381 
+382 #include <fstream>
+383 using std::ifstream;
+384 using std::ofstream;
+385 
+386 :(before "End Globals")
+387 //: In future layers we'll use the depth field as follows:
+388 //:
+389 //: Errors will be depth 0.
+390 //: Mu 'applications' will be able to use depths 1-100 as they like.
+391 //: Primitive statements will occupy 101-9989
+392 extern const int Initial_callstack_depth = 101;
+393 extern const int Max_callstack_depth = 9989;
+394 //: Finally, details of primitive Mu statements will occupy depth 9990-9999
+395 //: (more on that later as well)
+396 //:
+397 //: This framework should help us hide some details at each level, mixing
+398 //: static ideas like layers with the dynamic notion of call-stack depth.
+
+ + + -- cgit 1.4.1-2-gfad0