Add documentation about some structs/classes

src/codegen/irgen/hooks.cpp

@@ -772,11 +772,11 @@ CompiledFunction::CompiledFunction(llvm::Function* func, FunctionSpecialization*
                                    ExceptionStyle exception_style, const OSREntryDescriptor* entry_descriptor)
     : clfunc(NULL),
       func(func),
+      effort(effort),
+      exception_style(exception_style),
       spec(spec),
       entry_descriptor(entry_descriptor),
       code(code),
-      effort(effort),
-      exception_style(exception_style),
       times_called(0),
       times_speculation_failed(0),
       location_map(nullptr) {

src/core/stats.h

@@ -26,8 +26,10 @@
 
 namespace pyston {
 
+// Set this to 1 to disable all stats-related operations.  Shouldn't usually be necessary.
 #define DISABLE_STATS 0
 
+// Enable certain expensive stat collections:
 #define STAT_ALLOCATIONS (0 && !DISABLE_STATS)
 #define STAT_ALLOCATION_TYPES (0 && !DISABLE_STATS)
 #define STAT_CALLATTR_DESCR_ABORTS (0 && !DISABLE_STATS)
@@ -53,6 +55,8 @@ namespace pyston {
 #define STAT_TIMER_NAME(id) _st##id
 
 #if !DISABLE_STATS
+// The class that stores and manages stats collection.  For normal stats collections purposes,
+// you shouldn't have to use this class, and will usually want to use StatCounter instead.
 struct Stats {
 private:
     static std::unordered_map<uint64_t*, std::string>* names;
@@ -75,6 +79,22 @@ public:
     static void endOfInit();
 };
 
+// A helper class for efficient stats collections.  Typical usage:
+//
+//     static StatCounter my_stat_counter("my_informative_stat_name");
+//     void myFunction() {
+//         my_stat_counter.log();
+//     }
+//
+// The current convention for stat names is underscore_case, such as `num_cxa_throw`,
+// though at some point we'd like to move to a period-delimited convention.
+// (Run `./pyston -s` to see the list of current stats we log.)
+// For single stats, usually `num_foo` is a decent name.  If there are many stats in a
+// single category, you can drop the `num_`.
+// If a stat name is a prefix of another, the event it is counting should be a superset.
+// For instance, `ic_rewrites` counts a superset of the events that `ic_rewrites_aborted`
+// counts, which itself is a superset of the events that `ic_rewrites_aborted_assemblyfail`
+// counts.
 struct StatCounter {
 private:
     uint64_t* counter;
@@ -85,6 +105,11 @@ public:
     void log(uint64_t count = 1) { *counter += count; }
 };
 
+// Similar to StatCounter, but should be allocated as:
+//
+//     static thread_local StatPerThreadCounter my_stat_counter("cool_stat_name");
+//
+// This will automatically add the thread id to the stat name.
 struct StatPerThreadCounter {
 private:
     uint64_t* counter = 0;
@@ -117,6 +142,9 @@ struct StatPerThreadCounter {
 #endif
 
 #if STAT_TIMERS
+
+// StatTimers are for a specific type of profiling investigation.  Until we make this more usable,
+// there probably shouldn't be more changes or uses of this class.
 class StatTimer {
 private:
     static __thread StatTimer* stack;
@@ -226,6 +254,8 @@ public:
 
     static void assertActive() { ASSERT(stack && !stack->isPaused(), ""); }
 };
+
+// Helper class around a StatTimer
 class ScopedStatTimer {
 private:
     StatTimer timer;
@@ -237,6 +267,7 @@ public:
     }
     ~ScopedStatTimer() { timer.popNonTopLevel(); }
 };
+
 #else
 struct StatTimer {
     StatTimer(uint64_t*) {}

src/core/threading.h

@@ -138,6 +138,7 @@ void demoteGL();
 
 
 
+// Helper macro for creating a RAII wrapper around two functions.
 #define MAKE_REGION(name, start, end)                                                                                  \
     class name {                                                                                                       \
     public:                                                                                                            \

src/runtime/types.h

@@ -307,6 +307,10 @@ protected:
     friend void setupThread();
 };
 
+// Corresponds to PyHeapTypeObject.  Very similar to BoxedClass, but allocates some extra space for
+// structures that otherwise might get allocated statically.  For instance, tp_as_number for builtin
+// types will usually point to a `static PyNumberMethods` object, but for a heap-allocated class it
+// will point to `this->as_number`.
 class BoxedHeapClass : public BoxedClass {
 public:
     PyNumberMethods as_number;
@@ -336,6 +340,7 @@ private:
     friend void setupThread();
 };
 
+// Assert that our data structures have the same layout as the C API ones with which they need to be interchangeable.
 static_assert(sizeof(pyston::Box) == sizeof(struct _object), "");
 static_assert(offsetof(pyston::Box, cls) == offsetof(struct _object, ob_type), "");
 
@@ -675,7 +680,7 @@ public:
     // CPython declares ob_item (their version of elts) to have 1 element.  We want to
     // copy that behavior so that the sizes of the objects match, but we want to also
     // have a zero-length array in there since we have some extra compiler warnings turned
-    // on.  _elts[1] will throw an error, but elts[1] will not.
+    // on:  _elts[1] will throw an error, but elts[1] will not.
     union {
         Box* elts[0];
         Box* _elts[1];
@@ -687,6 +692,7 @@ static_assert(offsetof(BoxedTuple, elts) == offsetof(PyTupleObject, ob_item), ""
 
 extern BoxedString* characters[UCHAR_MAX + 1];
 
+// C++ functor objects that implement Python semantics.
 struct PyHasher {
     size_t operator()(Box* b) const {
         if (b->cls == str_cls) {
@@ -719,8 +725,11 @@ struct PyLt {
 
 // llvm::DenseMap doesn't store the original hash values, choosing to instead
 // check for equality more often.  This is probably a good tradeoff when the keys
-// are pointers and comparison is cheap, but we want to make sure that keys with
-// different hash values don't get compared.
+// are pointers and comparison is cheap, but when the equality function is user-defined
+// it can be much faster to avoid Python function invocations by doing some integer
+// comparisons.
+// This also has a user-visible behavior difference of how many times the hash function
+// and equality functions get called.
 struct BoxAndHash {
     Box* value;
     size_t hash;