πŸš€ An experimental Java virtual machine with bytecode interpreter for the educational purpose
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example refine code with Go 1.9 features Feb 22, 2018
jdk/classes Main class uses AppClassLoader to load Jul 31, 2017
src/jago minor fix Aug 31, 2018
.gitignore vgo support Sep 5, 2018
Jago-jdk.png refactor Jun 28, 2017
LICENSE Update LICENSE Aug 21, 2018
README.md update README Aug 30, 2018
build.sh vgo support Sep 5, 2018
cpu.pdf update README Aug 30, 2018
go.mod vgo support Sep 5, 2018
go.sum vgo support Sep 5, 2018
jago.pptx update presentation link Aug 22, 2018
main.go minor fix Aug 5, 2018

README.md

Jago

A simplified Java virtual machine written in Go language. One aim is to learn JVM specification in depth and try to understand the behind-the-scene behaviour when a Java program runs.

I only refer to "Java Virtual Machine Specification" and then look into how we should design one. Some production-level features are intentionally ignored and it is supposed to make it as simplified as possible so as to demonstrate the general idea. For the educational purpose, it is more than enough.

If you have no time to read OpenJDK source code or always guess the JVM behaviour when you need to tune your program, then your right here to be the lord of your universe.

Any thought is welcome and I am happy to be wrong.

Roadmap

  • Java class file reader
  • Interpreter engine
  • Class loader delegation
  • multi-threading support
  • monitor, sleep, wait, notify support
  • JDK native methods
  • GC
  • JIT

How to run

build and install

❯ cd ~/jago
❯ ./build.sh

By default, jago will be installed to /usr/local/jago

/usr/local/jago
β”œβ”€β”€ bin
β”‚Β Β  └── jago
β”œβ”€β”€ jdk
β”‚Β Β  └── classes
β”‚Β Β      β”œβ”€β”€ META-INF
β”‚Β Β      β”œβ”€β”€ apple
β”‚Β Β      β”œβ”€β”€ com
β”‚Β Β      β”œβ”€β”€ java
β”‚Β Β      β”œβ”€β”€ javax
β”‚Β Β      β”œβ”€β”€ jdk
β”‚Β Β      β”œβ”€β”€ org
β”‚Β Β      └── sun
└── log
    β”œβ”€β”€ classloader.log
    β”œβ”€β”€ io.log
    β”œβ”€β”€ misc.log
    β”œβ”€β”€ thread-bootstrap.log
    β”œβ”€β”€ thread-main.log
    └── threads.log

jago command

❯ jago -h
NAME:
   Jago - A simplified Java Virtual Machine for the educational purpose

USAGE:
   jago [-options] class [args...]

VERSION:
   1.0.0

DESCRIPTION:
   A Java Virtual Machine demonstrating the basic features of execution engine, class loading, type/value system, exception handling, native methods etc.

AUTHOR:
   Chao Yang <chaoyangnz@gmail.com>

COMMANDS:
     help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --classpath value, --cp value  application classpath separated by colon
   --noLogo, --nl                 don't show logo
   --debug, -d                    debug mode
   --trace, -t                    trace mode
   --log:thread value             log level of instruction execution in a thread context, options: info, debug, trace
   --log:classloader value        log level of class loading, options: info, debug, trace
   --profile, -p                  profile jago
   --help, -h                     show help
   --version, -v                  print the version

Run a calendar program

❯ jago --log:thread info -cp . Calendar 8 2018

Run a pyramid program

❯ jago --log:thread info -cp . Pyramid

run a program traversing a tree in the level order

❯ jago --log:thread info -cp . TreeLevelOrderTraverse

Run a program into exception

❯ jago --log:thread info -cp . test/test_athrow

More examples to demonstrate features

  • Print system properties
jago -d test.test_system_properties
  • Multi-threading
jago -d test.test_thread
jago -d Multithread
  • Thread sleep or wait / interrupt
jago -d SleepInterrupt
jago -d WaitInterrupt
  • Java monitor lock with synchronized
jago -d Counter
  • Java wait() and notify(), notifyAll()
jago -d ProducerConsumer

trace the execution

log/thread-[name].log

This log file records the each instruction execution and method call hierarchy within a thread context. Set the log level to info to view call hierarchy more clearly.

The blue diamond symbol πŸ”Ή means pure Java methods while the yellow one πŸ”Έ means native methods which is implemented within Jago internally.

The fire symbol πŸ”₯ means exception throwing (thrown by athrow bytecode, rethrown if uncaught or thrown by VM internally), while the blue water symbol πŸ’§ means an exception is caught by a method.

  • TRACE: log all low level bytecode instructions, method call and exception thrown/caught
  • DEBUG: only method call and exception thrown/caught
  • INFO: only exception thrown/caught info

log/classloader.log

This log file records the class loading process, including what triggers a class loading and when its class initialization method <clinit> is invoked. The trigger reason can be viewed after a class name.

log/threads.log

This log file records thread creation/exit information and object monitor enter/exit, thread sleep(), wait(), notify() etc.

log/io.log

This log file records I/O details around system interactions.

log/misc.log

Other trivial logs

Profiling

https://flaviocopes.com/golang-profiling/

  • run jago with -p option
  • go tool pprof --pdf /usr/local/bin/jago /var/../cpu.pprof > cpu.pdf

Documentation

Really sorry, I have no time to write documentation but it is in my plan. The Ebook about how it works internally is in progress: https://www.gitbook.com/book/richdyang/go-my-jvm