Table of Contents

• HipHop Staging
• Generating statements
• Dynamic Signal Names in Delay Expressions
• Generated Modules
• Dynamic Signal Names in Run Expressions
• Generated Interfaces
• Dynamic Program Modifications
• mach.getElementById(id)
• mach.appendChild(node, hhstmt)
• mach.removeChild(node, child)

HipHop Staging

 

Using staging requires familiarities with code generation and compilation techniques and a deep understanding of HipHop's behavior. HipHop beginners should refrain from using staging until they have acquired that knowledge.

HipHop is a staged programming language. That is, although hidden by the syntax, all HipHop programs are the result of a JavaScript execution and all HipHop programs are first class values in the JavaScript world.

From the JavaScript standpoint, the hiphop construct (see Syntax) is an expression, which evaluates to a HipHop programs. This value representing a HipHop program can be manipulated as any other JavaScript value. It can be stored in variables or data structures, passed and returned from functions, etc. For instance, evaluating the following program:

const f = hiphop fork { await (a.now); } par { await (b.now) };
console.log(f);

Displays something such as:

hiphop.FORK { ... }

A HipHop program being a JavaScript value, it can be used as any ordinary value. Hence, we can modify the previous example for:

function makeFork() {
   return hiphop fork { await (a.now); } par { await (b.now) };
}

const f = makeFork();

HipHop values can be assembled together to form more complex HipHop programs. Example:

const aa = hiphop { await (a.now) };
const ab = hiphop { await (be.now) };
function makeFork(s1, s2) {
   return hiphop fork { ${s1} } par { ${s2} };
}
const f = makeFork(aa, ab);

To use this program fragment it has be installed in a HipHop machine. This can be acheived with:

import * as hh from "@hop/hiphop";

const aa = hiphop { await (a.now) };
const ab = hiphop { await (be.now) };

function makeFork(s1, s2) {
   return hiphop fork { ${s1} } par { ${s2} };
}

const f = makeFork(aa, ab);

const prgm = hiphop module() {
  in a, b;
  ${f}
}

const m = new hh.ReactiveMachine(prgm);
m.react({a: 1, b: 2});

Generating statements

The HipHop syntax provides escapes that enable HipHop programs to be assembled from separately developed statements. Within HipHop, the escape sequence ${...} (similar to the escape sequence of JavaScript string templates), inserts a HipHop statement into the program being build. For instance, compare the two equivalent programs. The first one uses any stagging facility.

★ staging-abro.hh.js

import * as hh from "@hop/hiphop";

const hhfork = hiphop fork {
   await(A.now);
} par {
   await(B.now);
}

const hhdo = hiphop do {
   ${hhfork}
   emit O();
} every(R.now)

const prg = hiphop module() {
   in A; in B; in R; out O;

   ${hhdo}
}

export const mach = new hh.ReactiveMachine(prg, "STAGING-ABRO");

The second one, which executes similarly and produces the same result does not:

★ abro.hh.js

import * as hh from "@hop/hiphop";

const prg = hiphop module() {
   in A; in B; in R; out O;
                  
   do {
      fork {
         await (A.now);
      } par {
         await (B.now);
      }
      emit O();
   } every (R.now)
}

export const mach = new hh.ReactiveMachine(prg, "ABRO");

Note in this example, how HipHop statments are stored in JavaScript variables and then inserted into the main program.

Inside a Hiphop statement an escape sequence ${...} is replaced at compile-time by the corresponding value. The type of the inserted value depends on the context of the escape sequence.

• an array of statements, when used, after the fork keyword; of HipHop statement;
• a statement or an array of statements, when used inside a sequence;
• a string, when used in the signal position of an emit statement;
• a HipHop statement otherwise.

In the following example, the three arms of a fork construct are first stored in a JavaScript array and then inserted into the constructed HipHop program.

★ staging-abcro.hh.js

import * as hh from "@hop/hiphop";

const hhpar = [
   hiphop { await(A.now) },
   hiphop { await(B.now) }, 
   hiphop { await(C.now) }
   ]

const prg = hiphop module() {
   in A; in B; in C; in R; out O;
                        
   do {
      fork ${hhpar}
      emit O();
   } every (R.now)
}

export const mach = new hh.ReactiveMachine(prg, "STATING-ABCRO");

In the second example:

★ staging-emit-if2.hh.js

import * as hh from "@hop/hiphop";
import { format } from "util";

const sigA = "A";
const sigB = "B";
const sigC = "C";

hiphop module prg() {
   inout A, B, C;
   
   fork {
      loop {
         if (this[sigB].nowval > 3) emit ${sigA}();
         yield;
      }
   } par {
      loop {
         if (this[sigC].now) {
            emit ${sigB}(4);
         } else {
            emit ${sigB}(3);
         }
         yield;
      }
   }
}

export const mach = new hh.ReactiveMachine(prg);
mach.outbuf = "";
mach.debug_emitted_func = emitted => {
   mach.outbuf += format(emitted) + "\n";
}

mach.react()
mach.react()
mach.react("C")
mach.react()
mach.react("C")
mach.react("C")

The emit statements uses generated signal names.

This last example illustrates many of the staging features, included those described in the next sections. It shows how to generate a fork construct with as many branches as values contained in a JavaScript array. It shows how to wait for and emit signals whose names are generated.

★ staging-fork.hh.js

import * as hh from "@hop/hiphop";
import { format } from "util";

const Instruments = [ "violin", "piano", "trumpet", "sax" ];

function makeAwait(instruments) {
   return hiphop fork ${ instruments.map(val => hiphop {
      await (this[`${val}IN`].nowval);
      emit ${`${val}OUT`}(${val});
   }) }
}

hiphop module prg() {
   in ... ${ Instruments.map(i => `${i}IN`) };
   out ... ${ Instruments.map(i => `${i}OUT`) };
                        
   ${ makeAwait(Instruments) }
}

export const mach = new hh.ReactiveMachine(prg);
mach.outbuf = "";
mach.debug_emitted_func = emitted => {
   mach.outbuf += format(emitted) + "\n";
}

mach.react();
mach.react({ violinIN: true, saxIN: true });
mach.react({ pianoIN: true });
mach.react()

Dynamic Signal Names in Delay Expressions

When HipHop programs are generated dynamically using the staging facilities, it happens that delay expressions (e.g., used in if or await statements) should used dynamically generated signal names. This is accomplished using the JavaScript this[expre] syntax. For instance, in the following example:

★ staging-emit-if2.hh.js

import * as hh from "@hop/hiphop";
import { format } from "util";

const sigA = "A";
const sigB = "B";
const sigC = "C";

hiphop module prg() {
   inout A, B, C;
   
   fork {
      loop {
         if (this[sigB].nowval > 3) emit ${sigA}();
         yield;
      }
   } par {
      loop {
         if (this[sigC].now) {
            emit ${sigB}(4);
         } else {
            emit ${sigB}(3);
         }
         yield;
      }
   }
}

export const mach = new hh.ReactiveMachine(prg);
mach.outbuf = "";
mach.debug_emitted_func = emitted => {
   mach.outbuf += format(emitted) + "\n";
}

mach.react()
mach.react()
mach.react("C")
mach.react()
mach.react("C")
mach.react("C")

The two HipHop if statements uses dynamic signal expressions for refering to signals B and C.

Generated Modules

This example uses a module generator (the function Timer). HipHop modules are lexically scopped with regard to Hop environment so all the expressions they contain can refer to Hop variables bound in the environment. In this example, the function parameter timeout is used in the async form to set the timeout duration.

The new modules are directly created when run, using the dollar-form in the main HipHop program.

★ run3.hh.js

import * as hh from "@hop/hiphop";
import { format } from "util";

const gameTimeout = 100;

function Timer(timeout) { 
   return hiphop module() {
      out tmt;
      async (tmt) {
         this.timer = setTimeout(() => this.notify("ok"), timeout); 
      } kill { 
         clearTimeout(this.timer); 
      }
   }
}

const GT = Timer(gameTimeout);

hiphop module prg(resolve) {
   out O;
   signal tmt;
   
   fork {
      run GT() { * };
   } par {
      await (tmt.now);
      emit O(tmt.nowval);
   }
   pragma { resolve(false); }
}

export const mach = new hh.ReactiveMachine(prg);
mach.outbuf = "";
mach.debug_emitted_func = val => val;
mach.batchPromise = new Promise((res, rej) => mach.init(res));
mach.addEventListener("O", evt => mach.outbuf += evt.nowval + "\n");
mach.react();
mach.react();

The input/output signal declaration syntax enables staging. The ... form can be followed by a dollar expression that should evaluate to an array of strings that will denote the names of the declared signals.

★ Example: staging-incr-branch2.hh.js

import * as hh from "@hop/hiphop";

const sigs = [ "O", "P" ];

hiphop module prg() {
   out ... ${sigs} combine (x, y) => x + y;
   loop {
      fork "par" {
         emit O(1);
         emit P(1);
      }
      yield;
      yield;
   }
}

function add_emit(machine) {
   machine.getElementById("par").appendChild(hiphop { emit O(1); emit P(1); });
}

export const mach = new hh.ReactiveMachine(prg, { name: "incr-branch", sweep: false, dynamic: true });
mach.outbuf = "";
mach.debug_emitted_func = val => {
   mach.outbuf += (val.toString() ? "[ '" + val + "' ]\n" : "[]\n");
}

mach.react()
mach.react()
mach.react()
mach.react()
add_emit(mach);
mach.react()
mach.react()
mach.react()
add_emit(mach);
add_emit(mach);
add_emit(mach);
mach.react()
mach.react()

Dynamic Signal Names in Run Expressions

Signals aliased in a run command can declared with a dollar-form. This enables a generated signal name on the main module to be bound to a static signal name on the ran module. Example:

★ Example: run6.hh.js

import * as hh from "@hop/hiphop";

const MYSIG = "O";

hiphop module mod(n, m) {
   out O;
   emit O(n + m);
}
    
hiphop module prg() {
   out ${MYSIG} combine (x, y) => x + y;
   fork {
      run mod(10, 5) { ${MYSIG} as O };
   } par {
      run mod(100, 123) { * };
   }
}

export const mach = new hh.ReactiveMachine(prg);
mach.outbuf = "";
mach.addEventListener(MYSIG, evt => mach.outbuf += evt.nowval + "\n");
mach.react();

Generated Interfaces

Staged interfaces are created by using regular objects whose properites are HipHop signal descriptor. An signal descriptor is described by the following properties:

• direction: a string that might either be "IN", "OUT", or "INOUT";
• init: a JavaScript thunk (a function with no argument) that initializes the signal during the reaction;
• combine: an associated binary function used for multiple emissions during a reaction.
• transient: a boolean to declare transient signals, i.e., signales not preserving their nowval value accross instants.

In a run statement, the signal bindings can also being staged using JavaScript objects associating bound names. In these binding objects, special properties * and + play the same role as the * and + operators of the non-staged binders (see modules).

Example:

★ staging-interface.hh.js

import * as hh from "@hop/hiphop";

const I1 = {
   A: { direction: "INOUT", transient: true },
   B: { direction: "INOUT", transient: true },
   C: { direction: "INOUT", transient: true }
}

const I2 = Object.assign({D: { direction: "INOUT" }}, I1);

const bindings = {
   D: "Z",
   "*": true
};

hiphop module M2() implements I2 {
   emit A(10);
   emit D(23);
}

hiphop module M1() implements I1 {
   inout Z;
   run M2() ${bindings}
}

export const mach = new hh.ReactiveMachine(M1);
mach.outbuf = "";

mach.addEventListener("A", v => mach.outbuf += ("got A " + v.nowval) + "\n");
mach.addEventListener("Z", v => mach.outbuf += ("got Z " + v.nowval) + "\n");

mach.react();

which can be compared to the non-staged version:

★ interface.hh.js.

import * as hh from "@hop/hiphop";

hiphop interface I1 { inout A, B, C; };
hiphop interface I2 extends I1 { inout D; };

hiphop module M2() implements I2 {
   emit A(10);
   emit D(23);
}

hiphop module M1() implements I1 {
   inout Z;
   run M2() { Z as D, * }
}

export const mach = new hh.ReactiveMachine(M1);
mach.outbuf = "";

mach.addEventListener("A", v => mach.outbuf += ("got A " + v.nowval) + "\n");
mach.addEventListener("Z", v => mach.outbuf += ("got Z " + v.nowval) + "\n");

mach.react();

Dynamic Program Modifications

HipHop fork and sequence statements can be modified in between two reactions using the function appendChild.

mach.getElementById(id)

Returns the HipHop fork or sequence labeld with id.

mach.appendChild(node, hhstmt)

Append a child to a statement. If node is a fork construct, the child is added as a new parallel branch. If node is a sequence, the child is added after the node children.

mach.removeChild(node, child)

Remove a child.

★ Example appendseqchild.hh.js

import * as hh from "@hop/hiphop";

function makePar(x, y) {
   return hiphop fork {
      pragma { x() }
   } par {
      pragma { y() }
   }
}

hiphop module main() {
   "myseq" {
      loop {
        pragma { mach.outbuf += "a\n" }
        yield;
        pragma { mach.outbuf += "b\n" }
        yield;
        pragma { mach.outbuf += "c\n" }
        yield;
      }
   }
}

export const mach = new hh.ReactiveMachine(main, { name: "appendseqchild", sweep: false, dynamic: true });
mach.outbuf = "";
mach.react();

const seq = mach.getElementById("myseq");

seq.appendChild(makePar(() => mach.outbuf += "p1\n", () => mach.outbuf += "p2\n"));

mach.react();
mach.react();

---

[main page] | [documentation] | [license]