RustViz

RustViz is a tool written in Rust that generates visualizations from simple Rust programs to assist potential users and students in better understanding the Rust Lifetime and Borrowing mechanism.

Documentation

• Example Usage
• User Define Usage
• Data Structure and Function Specifications
• Modules
• Visulization Limitations

What does it look like?

RustViz generates .svg files of graphical indicators that integrate with mdbook to generate visualization over user-defined rust code examples. Here's a sample view of what the visualization looks like:

Example Usage

RustViz is capable of visualizing simple rust codes (refer to the restriction section) via user definition. In this section we'll showcase how to generate some default visulization example that has been provided by us.

RustViz requires Rust, Cargo and mdbook to be installed. Once you have installed all the above prerequisites, direct into the /test_example folder and run test_examples.sh

./test_examples.sh

You may have the a output that's similar to this:

Generating visualizations for the following examples: 
building hatra1...
building hatra2...
building string_from_print...
building string_from_move_print...
building func_take_ownership...
building immutable_borrow...
building multiple_immutable_borrow...
building mutable_borrow...
building nll_lexical_scope_different...
building move_different_scope...
building move_assignment...
building move_func_return...
building func_take_return_ownership...
building immutable_borrow_method_call...
building mutable_borrow_method_call...
building immutable_variable...
building mutable_variables...
building copy...
building function...
building printing...
2021-01-19 12:36:13 [INFO] (mdbook::book): Book building has started
2021-01-19 12:36:13 [INFO] (mdbook::book): Running the html backend
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

If you observed this output, then you have successfully generated the rust visulization examples! Now open your brower and browse into http://localhost:8000/. You should be able to view all the examples by selecting each from the list bar on the left. To enable visulization, toggle the swtich that is included in the code section.

Great! Now you've know how to generate and view the visualization that you could create by using RustViz, Now let's create one of your own!

User Define Usage

In this section, we'll take a look into how to create example by using our example string_from_move_print. let's first take a look at the file structure you need for the example to run:

string_from_move_print
├── input
│   └── annotated_source.rs
├── main.rs
└── source.rs

let's first take a look at the source.rs, which is simply the rust source code that we are generating visulization from:

fn main() {
    let x = String::from("hello");
    let y = x;
    println!("{}", y)
}

In this example, the string hello's resource is first moved from String::from() to x, then x's resource is moved to y. Lastly, we print the value by taking y as an input to println!() but the resource has not been moved.

Next, let's focus on we need to do in main.rs. In this visuliation tool, we define all possible owners, references or input of any memory resource as a Resource Access Point. In this case, we have the function String::from() and two variables x and y as Resource Access Points. Correspondingly in our implementation, the Resource Access Point is defined as an enum that hold the possible types of Resource Access Points, namely ResourceAccessPoint::Owner and ResourceAccessPoint::Function in this case. We want to create instance that represent these functions and variables in our main program:

// Variables
    let x = ResourceAccessPoint::Owner(Owner {
        hash: 1,
        name: String::from("x"),
        is_mut: false,
        lifetime_trait: LifetimeTrait::Move
    });
    let y = ResourceAccessPoint::Owner(Owner {
        hash: 2,
        name: String::from("y"),
        is_mut: false,
        lifetime_trait: LifetimeTrait::Move
    });
// Functions
    let from_func = ResourceAccessPoint::Function(Function {
        hash: 5,
        name: String::from("String::from()"),
    });

Next we decalre an instance of the VisualizationData struct as a container that holds all the information of ExternalEvent that we will talk about up next, all you need is to declare the struct instance without any modification:

let mut vd = VisualizationData {
    timelines: BTreeMap::new(),
    external_events: Vec::new(),
    preprocess_external_events: Vec::new(),
    event_line_map: BTreeMap::new()
};

The ExternalEvent is an enum that hold all the movement, borrowing and dropping of a resource. In our case, we have four of such event:

1. Resource was moved from String::from() to x
2. Resource was moved from y to x
3. Resource of x is dropped
4. Resource of y is dropped

We then add these events information to the VisualizationData instance we declared before by using the append_external_event() function:

// Resource was moved from `String::from()` to `x`
    vd.append_external_event(ExternalEvent::Move{from: Some(from_func.clone()),
        to: Some(x.clone())}, &(2 as usize));
// Resource was moved from `y` to `x`
    vd.append_external_event(ExternalEvent::Move{from: Some(x.clone()),
        to: Some(y.clone())}, &(3 as usize));
// Resource of `x` is dropped
    vd.append_external_event(ExternalEvent::GoOutOfScope{ ro: x }, &(5 as usize));
// Resource of `y` is dropped
    vd.append_external_event(ExternalEvent::GoOutOfScope{ ro: y }, &(5 as usize));

Now the final step is to activte the rendering function that generate the vis_code.svg and vis_timeline.svg that are visulization SVG files for the code section and timeline section using the svg_generation::render_svg() function:

svg_generation::render_svg(&"examples/string_from_move_print/input/".to_owned().to_owned(), &"examples/string_from_move_print/".to_owned(), & mut vd);

Phew! Good Work! What's left is to run the program. Direct into the /svg_generator folder and run

cargo run --example string_from_move_print

Now your folder should look like this:

string_from_move_print
├── input
│   └── annotated_source.rs
├── main.rs
├── source.rs
├── vis_code.svg
└── vis_timeline.svg

Congratulations! You have Successfully generated the visulizations! Add the name of your example folder to /test_example/test_examples.sh and see them in your browser.

Data Structures and Function Specifications

• Resource Access Point
  • Owner
  • Struct
  • Mutable reference and Inmutable reference
  • Functions
• External Events
  • Duplicate
  • Move
  • Static Borrow
  • Mutable Borrow
  • Static Return
  • Mutable Return
  • Pass By Static Reference
  • Pass By Mutable Reference
  • Go Out Of Scope
  • Initialize Param

• ResourceAccessPoint ResourceAccessPoint is an enum that define all possible owner, references or creator of any memory resource. For now, the types of ResourceAccessPoint could possibly be an owner of a resource, a mutable reference of a resource, a unmutable referene of a resource or a function:

  pub enum {
      Owner(Owner),
      MutRef(MutRef),
      StaticRef(StaticRef),
      Function(Function),
  }
  

  • Owner For the owner of a resource, we need to define several properties: The name of the variable, the hash number and whether the vairable is mutable. The lifetime_trait property is not yet implemented.

    pub struct Owner {
        pub name: String,
        pub hash: u64,
        pub is_mut: bool, // let a = 42; vs let mut a = 42;
        pub lifetime_trait: LifetimeTrait,
    }
    

  • Struct For the owner and members of a struct, we need to define several properties: The name of the variable, the hash number of itself and its owner, if it is a member and whether the vairable is mutable. The lifetime_trait property is not yet implemented.

    pub struct Owner {
        pub name: String,
        pub hash: u64,
        pub owner: u64, // if it is the owner, then keep it the same as hash of itself
        pub is_mut: bool, // let a = 42; vs let mut a = 42;
        pub lifetime_trait: LifetimeTrait,
        pub is_member: bool, 
    }
    

  • Mutable reference and Inmutable reference The defintion for references are similar to that of a Owner, but additionally we need to define the my_owner_hash, which refer back to the hash number of its owner. We also need to define is_mut, which represent the mutability of the reference. The lifetime_trait property is not yet implemented.

    // a reference of type &mut T
    #[derive(Clone, Hash, PartialEq, Eq, Debug)]
    pub struct MutRef {         // let (mut) r1 = &mut a;
        pub name: String,
        pub hash: u64,
        pub my_owner_hash: Option<u64>,
        pub is_mut: bool,
        pub lifetime_trait: LifetimeTrait,
    }
    
    // a reference of type & T
    #[derive(Clone, Hash, PartialEq, Eq, Debug)]
    pub struct StaticRef {                // let (mut) r1 = & a;
        pub name: String,
        pub hash: u64,
        pub my_owner_hash: Option<u64>,
        pub is_mut: bool,
        pub lifetime_trait: LifetimeTrait,
    }
    

  • Functions For each function, we only need to specify its name and hash number.

    pub struct Function {
        pub name: String,
        pub hash: u64,
    }
    

• ExternalEvents ExternalEvents is an enum that hold all the movements of a the resource, here is the list of all the possible movements are avaliable for visualization:

  • Duplicate The Duplicate event represent the copy of one variable to the other that does not involve the move of resource.

    Duplicate {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>,
    },
    

    User case:

    let y = 5; // Duplicate from None to y 
    // set from Option to None to represent initialization
    let x = y; // Duplicate from y to x
    

  • Move The Move event represent the tranferring of resource from one detination to the other.

    Move {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>,
    },
    

    User case:

    let x = String::from("Hello"); // Move from String::from() to x
    let y = x; // Move from x to y
    

  • StaticBorrow The StaticBorrow event represent the immutable borrowing in rust

    StaticBorrow {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>,
    },
    

    User case:

    let x = String::from("hello");
    let y = &x; // immutable borrow from x to y
    

  • MutableBorrow The MutableBorrow event represent the mutable borrowing in rust

    MutableBorrow {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>,
    },
    

    User case:

    let mut x = String::from("Hello");
    let y = &mut x; // mutable borrow from x to y
    

  • StaticDie The StaticDie event represent return of a unmutably borrowed source.

    StaticDie {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>,
    },
    

    User case:

    fn main() {
        let z = &mut x;
        world(z); // return mutably borrowed source from z to x since z is no longer used
    }
    fn world(s : &mut String) { 
        s.push_str(", world")
    }
    

  • MutableDie The MutableDie event represent return of a mutably borrowed source.

    MutableDie {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>,
    },
    

    User case:

    fn main() {
        let y = &x
        let z = &x;
        f(y, z); // return immutably borrowed source from z to x since z is no longer used
        // also return immutably borrowed source from y to x since y is no longer used
    }
    fn f(s1 : &String, s2 : &String) { 
        println!("{} and {}", s1, s2)
    }
    

  • PassByStaticReference The PassByStaticReference event represent passing an inmutable reference to a function.

    PassByStaticReference {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>, // must be a function
    },
    

    User case:

    fn main() {
        let x = String::from("hello"); 
        f(&x); // f() could only read from x
    }
    fn f(s : &String) { 
        println!("{}", s) 
    } 
    

  • PassByMutableReference The PassByMutableReference event represent passing a mutable reference to a function.

    PassByMutableReference {
        from: Option<ResourceAccessPoint>,
        to: Option<ResourceAccessPoint>, // must be a function
    },
    

    User case:

    fn main() {
        let z = &mut x;
        world(z); // world() could read from/write to z
    }
    fn world(s : &mut String) { 
        s.push_str(", world")
    }
    

  • GoOutOfScope The GoOutOfScope event represent a variable go out of scope.

    GoOutOfScope {
        ro: ResourceAccessPoint // must be a variable
    },
    

    User case:

    fn main() { 
        let x = 5; 
        let y = x; // x and y both go out of scope
    } 
    

  • InitRefParam The InitRefParam event represent initialization of the parameters within a function

    InitRefParam {
        param: ResourceAccessPoint, // the parameter in function
    }
    

    User case:

    fn takes_ownership(some_string: String) { // initialize some_string
        println!("{}", some_string) 
    } 
    

Modules

1. mdbook_plugin

   a. book.js:

   Relevant Lines	Purpose
   18-42	adjust_visualization_size(): Responsible for automatically resizing visualization flexboxes on page load.
   228-283	Responsible for adding toggle buttons to every code block that contains a corresponding visualization.

   b. helpers.js: responsible for dynamic/interactive portions of the visualization, from hover messages to word highlighting.

   c. visualization.css: defines page's flexbox styling

2. svg_generator

   a. examples: contains all examples to be rendered

    Folder structure for new examples:
        <example_name>
        ├── input
        │   └── annotated_source.rs
        ├── main.rs
        ├── source.rs
        ├── vis_code.svg
        └── vis_timeline.svg
   

   File	Purpose
   annotated_source.rs	Adds styling to code panel with the use of <tspan> tags Properties of Variables: data-hash Properties of Functions: hash, data-hash="0", class="fn"
   main.rs	Defines all ResourceAccessPoint types and events
   source.rs	Contains original, source code that will be rendered into SVG
   vis_code.svg	(1/2) Final rendered SVG code panel
   vis_timeline.svg	(2/2) Final rendered SVG timeline panel with arrows, dots, etc

   b. src

   File	Purpose
   data.rs	Defines all ResourceAccessPoint types and is responsible for calculating transition between states
   hover_messages.rs	Contains all hover message templates
   code_panel.rs code_template.svg	Defines template for code panel and builds corresponding SVG renderings
   timeline_panel.rs timeline_template.svg	Defines template for timeline panel and builds corresponding SVG renderings
   svg_generation.rs	Renders source code to SVG images and saves them under respective directory in svg_generator/examples/
   line_styles.rs	Unused

Visualization Limitations

Yet to be finished....