Style and document call graph

Author: smowton

src/analyses/call_graph.cpp

@@ -123,11 +123,11 @@ void call_grapht::output_dot(std::ostream &out) const
 
 
 void call_grapht::output_dot(
-  goto_functionst const &functions,
+  const goto_functionst &functions,
   std::ostream &out) const
 {
   out << "digraph call_graph {\n";
-  for(auto const &elem : functions.function_map)
+  for(const auto &elem : functions.function_map)
     out << "  \"" << elem.first << "\";\n";
   for(grapht::const_iterator it=graph.begin();
       it!=graph.end();
@@ -186,26 +186,52 @@ void call_grapht::output_xml(std::ostream &out) const
   }
 }
 
+/*******************************************************************\
+
+Function: call_grapht::out_edges
+
+  Inputs: `caller`: node to search for
+
+ Outputs: Returns list of edges whose first component is `caller`.
+
+ Purpose:
+
+\*******************************************************************/
 
 call_grapht::call_edges_ranget
-call_grapht::out_edges(irep_idt const &caller) const
+call_grapht::out_edges(const irep_idt &caller) const
 {
   return graph.equal_range(caller);
 }
 
+/*******************************************************************\
+
+Function: inverted_partial_topological_order
+
+  Inputs: `call_graph`: Call graph
+          `start_function`: start node, must occur in call graph
+          `processed_functions`: set of functions already seen
 
-void  inverted_partial_topological_order(
-  call_grapht const &call_graph,
-  irep_idt const &start_function,
+ Outputs: `output`: inverted topological sort of the graph reachable
+            from start node (i.e. leaves first, root last)
+          `processed_functions`: set of functions already seen
+
+ Purpose: Get reverse-top-sorted subgraph
+
+\*******************************************************************/
+
+void inverted_partial_topological_order(
+  const call_grapht &call_graph,
+  const irep_idt &start_function,
   std::unordered_set<irep_idt, dstring_hash> &processed_functions,
   std::vector<irep_idt> &output)
 {
-  if(processed_functions.count(start_function) != 0ULL)
+  if(processed_functions.count(start_function)!=0ULL)
     return;
   processed_functions.insert(start_function);
-  call_grapht::call_edges_ranget const  range =
+  const call_grapht::call_edges_ranget range =
     call_graph.out_edges(start_function);
-  for(auto  it = range.first; it != range.second; ++it)
+  for(auto it=range.first; it!=range.second; ++it)
     inverted_partial_topological_order(
       call_graph,
       it->second,
@@ -214,99 +240,206 @@ void  inverted_partial_topological_order(
   output.push_back(start_function);
 }
 
+/*******************************************************************\
+
+Function: get_inverted_topological_order
+
+  Inputs: `call_graph`: Call graph
+          `functions`: map containing all functions of interest;
+            only function names are used to index into call graph;
+            function bodies are ignored.
+
+ Outputs: `output`: inverted topological sort of the graph reachable
+            from start node (i.e. leaves first, root last)
+
+ Purpose: Get reverse-top-sorted call graph
+
+\*******************************************************************/
+
 void get_inverted_topological_order(
-  call_grapht const& call_graph,
-  goto_functionst const& functions,
+  const call_grapht& call_graph,
+  const goto_functionst& functions,
   std::vector<irep_idt>& output)
 {
-  std::unordered_set<irep_idt, dstring_hash>  processed;
-  for(auto const &elem : functions.function_map)
+  std::unordered_set<irep_idt, dstring_hash> processed;
+  for(const auto &elem : functions.function_map)
     inverted_partial_topological_order(
       call_graph,
       elem.first,
       processed,
       output);
 }
 
+/*******************************************************************\
+
+Function: exists_direct_call
+
+  Inputs: `call_graph`: Call graph
+          `caller`: Caller
+          `callee`: Potential callee
+
+ Outputs: Returns true if call graph says caller calls callee.
+
+ Purpose: See output
+
+\*******************************************************************/
+
+
 bool exists_direct_call(
-  call_grapht const &call_graph,
-  irep_idt const &caller,
-  irep_idt const &callee)
+  const call_grapht &call_graph,
+  const irep_idt &caller,
+  const irep_idt &callee)
 {
-  call_grapht::call_edges_ranget const  range =
+  const call_grapht::call_edges_ranget range =
     call_graph.out_edges(caller);
-  for(auto  it = range.first; it != range.second; ++it)
-    if(callee == it->second)
+  for(auto it=range.first; it!=range.second; ++it)
+    if(callee==it->second)
       return true;
   return false;
 }
 
+/*******************************************************************\
+
+Function: exists_direct_or_indirect_call
+
+  Inputs: `call_graph`: Call graph
+          `caller`: Caller
+          `callee`: Potential callee
+          `ignored_functions`: Functions to exclude from call graph
+            for the purposes of finding a path
+
+ Outputs: Returns true if call graph says caller can reach callee
+          via any intermediate sequence of callees not occurring
+          in ignored_functions
+
+ Purpose: See output
+
+\*******************************************************************/
+
 bool exists_direct_or_indirect_call(
-  call_grapht const &call_graph,
-  irep_idt const &caller,
-  irep_idt const &callee,
+  const call_grapht &call_graph,
+  const irep_idt &caller,
+  const irep_idt &callee,
   std::unordered_set<irep_idt, dstring_hash> &ignored_functions)
 {
-  if(ignored_functions.count(caller) != 0UL)
+  if(ignored_functions.count(caller)!=0UL)
     return false;
   ignored_functions.insert(caller);
   if(exists_direct_call(call_graph, caller, callee))
-    return ignored_functions.count(callee) == 0UL;
-  call_grapht::call_edges_ranget const  range =
+    return ignored_functions.count(callee)==0UL;
+  const call_grapht::call_edges_ranget range=
     call_graph.out_edges(caller);
-  for(auto  it = range.first; it != range.second; ++it)
+  for(auto it=range.first; it!=range.second; ++it)
     if(exists_direct_or_indirect_call(
-          call_graph,
-          it->second,
-          callee,
-          ignored_functions))
+         call_graph,
+         it->second,
+         callee,
+         ignored_functions))
       return true;
   return false;
 }
 
+/*******************************************************************\
+
+Function: exists_direct_or_indirect_call
+
+  Inputs: `call_graph`: Call graph
+          `caller`: Caller
+          `callee`: Potential callee
+
+ Outputs: Returns true if call graph says caller can reach callee
+          via any intermediate sequence of callees
+
+ Purpose: See output
+
+\*******************************************************************/
+
 bool exists_direct_or_indirect_call(
-  call_grapht const &call_graph,
-  irep_idt const &caller,
-  irep_idt const &callee)
+  const call_grapht &call_graph,
+  const irep_idt &caller,
+  const irep_idt &callee)
 {
   std::unordered_set<irep_idt, dstring_hash>  ignored;
   return exists_direct_or_indirect_call(call_graph, caller, callee, ignored);
 }
 
+/*******************************************************************\
+
+Function: computed_inverted_call_graph
+
+  Inputs: `original_call_graph`: call graph
+
+ Outputs: `output_inverted_call_graph`: input call graph with caller->
+   callee edges reversed.
+
+ Purpose: See output
+
+\*******************************************************************/
+
 void compute_inverted_call_graph(
-  call_grapht const &original_call_graph,
+  const call_grapht &original_call_graph,
   call_grapht &output_inverted_call_graph)
 {
   assert(output_inverted_call_graph.graph.empty());
-  for(auto const &elem : original_call_graph.graph)
+  for(const auto &elem : original_call_graph.graph)
     output_inverted_call_graph.add(elem.second, elem.first);
 }
 
-void find_leaves_bellow_function(
-  call_grapht const &call_graph,
-  irep_idt const &function,
+/*******************************************************************\
+
+Function: find_leaves_below_function
+
+  Inputs: `call_graph`: call graph
+          `function`: start node
+          `to_avoid`: functions already visited
+
+ Outputs: `output`: set of leaves reachable from 'function'
+          `to_avoid`: functions already visited (with 'function'
+            added)
+
+ Purpose: See output
+
+\*******************************************************************/
+
+
+void find_leaves_below_function(
+  const call_grapht &call_graph,
+  const irep_idt &function,
   std::unordered_set<irep_idt, dstring_hash> &to_avoid,
   std::unordered_set<irep_idt, dstring_hash> &output)
 {
-  if(to_avoid.count(function) != 0UL)
+  if(to_avoid.count(function)!=0UL)
     return;
   to_avoid.insert(function);
-  call_grapht::call_edges_ranget const  range =
+  const call_grapht::call_edges_ranget range =
     call_graph.out_edges(function);
-  if(range.first == range.second)
+  if(range.first==range.second)
     output.insert(function);
   else
   {
-    for(auto  it = range.first; it != range.second; ++it)
-      find_leaves_bellow_function(call_graph, it->second, to_avoid, output);
+    for(auto it=range.first; it!=range.second; ++it)
+      find_leaves_below_function(call_graph, it->second, to_avoid, output);
   }
 }
 
+/*******************************************************************\
+
+Function: find_leaves_below_function
+
+  Inputs: `call_graph`: call graph
+          `function`: start node
+
+ Outputs: `output`: set of leaves reachable from 'function'
+
+ Purpose: See output
+
+\*******************************************************************/
+
 void find_leaves_below_function(
-  call_grapht const &call_graph,
-  irep_idt const &function,
+  const call_grapht &call_graph,
+  const irep_idt &function,
   std::unordered_set<irep_idt, dstring_hash> &output)
 {
   std::unordered_set<irep_idt, dstring_hash> to_avoid;
-  find_leaves_bellow_function(call_graph, function, to_avoid, output);
+  find_leaves_below_function(call_graph, function, to_avoid, output);
 }