Home - craterdog-archives/js-bali-virtual-machine GitHub Wiki

Musings

Robin's Egg

"From simple stirrings 'neath turquoise shell, springs complexity beyond Imagination" —the craterdog

Welcome

You have arrived at version 2 of the Bali Virtual Machine™ project. Whereas, the Bali Document Repository™ implements the structural aspects of the Bali Nebula™, the Bali Virtual Machine™ implements the procedural aspects.

Pyramid

This project defines a virtual processor that is used by the Bali Virtual Machine™ to process messages that have been sent to components defined using the Bali Component Framework™.

Each component has a type that is defined in a type document residing in the Bali Document Repository™. The type document defines a separate procedure for each type of message that can be sent to a component of that type. Each procedure describes the processing that should occur when the component receives a message of that type.

Type documents are themselves components written in Bali Document Notation™ Each type document has been compiled using the Bali Type Compiler™ which generates machine instructions in Bali Instruction Notation™ for each procedure.

The machine instructions are then assembled using the Bali Instruction Assembler™ which generates the bytecode that should be executed by a virtual processor for each type of message.

A Requisite "Hello World!" Example

Even though we will never be explicitly writing assembly language for the Bali Virtual Machine™, the following example shows the machine instructions that implement a "Hello World!" example.

    1.PublishStatement:
    NOTE --Save the name of the global event bag.
    PUSH LITERAL `/nebula/vm/events/v1`
    SAVE VARIABLE $bag-2
    NOTE --Publish an event to the global event bag.
    PUSH LITERAL `"Hello World!"`
    SAVE MESSAGE $bag-2
    LOAD VARIABLE $result-1
    PULL RESULT

These machine instructions were generated by the compiler from the following line of Bali Document Notation™.

publish "Hello World!"

But what the virtual machine sees is only the resulting bytecode.

28048001280C980160025000

which can be deconstructed as...

 Addr     Bytes   Bytecode     Instruction
---------------------------------------------
[001]:    2804    11    4    PUSH LITERAL 4
[002]:    8001    40    1    SAVE VARIABLE 1
[003]:    280C    11   12    PUSH LITERAL 12
[004]:    9801    43    1    SAVE MESSAGE 1
[005]:    6002    30    2    LOAD VARIABLE 1
[006]:    5000    22    0    PULL RESULT

The Instruction Set

There are only eight types of instructions in the Bali Virtual Machine™ instruction set. It was designed to be simple and operates at a higher level of abstraction than most virtual machine instruction sets.

  • JUMP - move the address pointer to the specified address either conditionally or unconditionally.
  • PUSH - push an item (handler, literal, constant, or argument) onto the stack.
  • PULL - pull the top item (handler, component, result, or exception) off of the stack.
  • LOAD - load onto the stack an item from the environment (variable, document, contract, or message).
  • SAVE - save the top item from the stack into the environment as a (variable, document, contract, or message).
  • DROP - drop from the environment an item (variable, document, contract, or message).
  • CALL - call an intrinsic function with zero to three arguments.
  • SEND - send a message to a target component or document with optional arguments.

An additional NOTE instruction is used to comment the code as seen in the example above. And finally, any instruction may be prefixed by a label (also shown in the example) that is referenced by one or more JUMP instructions. And that is all there is to the instruction set!

In Summary

The Bali Virtual Machine™ processes messages that are targeted for specific components (documents stored in the Bali Document Repository™) by executing the bytecode associated with message defined in the type document for the target component.

Version 2 is the first stable version of the virtual machine. There are likely be many bugs remaining in the code so watch for minor releases which fix bugs and add functionality, and for emergency bug patches. Minor releases (e.g. v2.x) and emergency bug patches (e.g. v2.x.y) should never break the public interface for the virtual machine.

To dive in deeper on the parts of the virtual machine that interest you most, click on links listed in the side bar in the upper right corner ↗️ of this page.