ROSE Compiler Framework/Abstract handles

From Wikibooks, open books for an open world
Jump to navigation Jump to search


This work is used in the autotuning and also other tools that pass references to source code as part of an interface.

  • essentially it defines ways to create a string to uniquely identify a language construct in your source code
  • any tool then can locate the corresponding node in AST and do the targetted analysis or transformation for you.

Abstract handles support the following forms for specifying language constructs:

  • Source file position information including path, filename, line and column number etc. GNU standard source position from presents some examples.
  • Global or local numbering of specified language construct in source file (e.g. 2nd ”do” loop in a global scope). The file is itself specified using an abstract handle (typically generated from the file name).
  • Global or local names of constructs. Some language constructs, such as files, function definitions and namespace, have names which can be used as their handle within a context.
  • Language-specific label mechanisms. These include named constructs in Fortran, numbered labels in Fortran, and statement labels in C and C++, etc.

In addition to human-readable forms, compilers and tools can generate internal IDs for language constructs. It is up to compiler/tool developers to provide a way to convert their internal representations into human-readable formats.


outline the for loop at line 12 of the input code

  • ./outline -rose:outline:abstract_handle "ForStatement<position,12>" -c $(srcdir)/inputCode_OutlineLoop2.c

Outline the 2nd for statement within a function named initialize() from the input code

  • ./outline -rose:outline:abstract_handle "FunctionDeclaration<name,initialize>::ForStatement<numbering,2>" -c $(srcdir)/inputCode_OutlineLoop2.c -rose:output rose_inputCode_OutlineLoop2b.c

Outline the statement at line 5 of the input code

  • ./outline -rose:outline:abstract_handle "Statement<position,5>" -c $(srcdir)/declarations.c

Key info[edit]

code sample[edit]

How to support abstract handles in your tool

#include "rose.h"
#include <string>
#include <iostream>
#include "commandline_processing.h"

using namespace std;
using namespace AbstractHandle;

int main(int argc, char * argv[])

  std::string handle;
  int factor =2;
  // command line processing
  vector<std::string> argvList (argv, argv+argc);
  if (!CommandlineProcessing::isOptionWithParameter (argvList,"-rose:loopcollapse:","abstract_handle",handle, true)
     || !CommandlineProcessing::isOptionWithParameter (argvList,"-rose:loopcollapse:","factor",factor, true))
     cout<<"Usage: loopCollapsing inputFile.c -rose:loopcollapse:abstract_handle <handle_string> -rose:loopcollapse:factor N"<<endl;
     return 0;

  // Retrieve corresponding SgNode from abstract handle
  SgProject *project = frontend (argvList);
  SgStatement* stmt = NULL;
  ROSE_ASSERT(project != NULL);
  SgFilePtrList & filelist = project->get_fileList();
  SgFilePtrList::iterator iter= filelist.begin();
  for (;iter!=filelist.end();iter++)
    SgSourceFile* sfile = isSgSourceFile(*iter);
    if (sfile != NULL)
      // prepare a file handle first
      abstract_node * file_node = buildroseNode(sfile);
      ROSE_ASSERT (file_node);
      abstract_handle* fhandle = new abstract_handle(file_node);
      ROSE_ASSERT (fhandle);
      // try to match the string and get the statement handle
      std::string cur_handle = handle;
      abstract_handle * shandle = new abstract_handle (fhandle,cur_handle);
      // it is possible that a handle is created but no matching IR node is found
      if (shandle != NULL)
        if (shandle->getNode() != NULL)
        { // get SgNode from the handle
          SgNode* target_node = (SgNode*) (shandle->getNode()->getNode());
          stmt = isSgStatement(target_node);
    } //end if sfile
  } // end for
  if (stmt==NULL)
    cout<<"Cannot find a matching target from a handle:"<<handle<<endl;
    return 0;

 if (isSgForStatement(stmt))
    bool result=false;
    SgForStatement *target_loop = isSgForStatement(stmt);
    result = SageInterface::loopCollapsing(target_loop, factor);
    ROSE_ASSERT(result != false);

  // Generate source code from AST and call the vendor's compiler
  return backend(project);


To cite the abstract handle work, please use the following paper in which the handles were first published:

  • Chunhua Liao, Daniel J. Quinlan, Richard Vuduc and Thomas Panas, Effective Source-to-Source Outlining to Support Whole Program Empirical Optimization, The 22nd International Workshop on Languages and Compilers for Parallel Computing (LCPC), Newark, Delaware, USA. October 8-10, 2009