[bundle] Request-Response centric construct for improvement of Diagrams

[mkhubaibumer]

Bundle Proposal

Description

This proposal depicts the core idea for a bundle in Lingua-Franca

---

This proposal makes three additions to LF Grammar

• Addition of new keyword bundle to create a bundle entity.
  
  • Bundles allow Generics so that a Default bundle with single input single output is provided as builtin
    
• Addition of new keyword Flipped OR Mirrored which is a code generator hint to make input as output and vice-versa
  
• Addition of port keyword to declare a bundle
  
  • This declaration will use the current semantics with the addition of Generic Typenames
    
    port comm:{Bundle-Name}<...>
    

---

This proposal also advises changes to the Language Server as follows:

• bundle to bundle implicit wiring will only result in a single bidirectional arrow
  
  • example:
    c.com <-> s.com
    
• explicit port to port wiring from bundle will result in as many uni-directional arrows as required (current design)
  
  
  • example:
    c.com.request -> s.com.request
s.com.response -> c.com.response
    

---

Why Not Inheritance?

A component can have multiple request/response pairs

In case of Inheritance that doesn't work in a reuse-able fashion.

In the case of Inheritance the Child Reactor will only have one instance of Parent's definition

Even a simple generic bundle with single input single output can be declared n-times
in a reactor with different names for n-components

• Impossible Case with Inheritance

  • bundle Default <I, O> {
       input in:I;
       output out:O;
    }
    reactor HashTable<KeyType, ElementType>(n_triggers:int(1)) {
       port bundle[n_triggers] add:Default<ElementType, bool>; // add entry to HashTable
       port bundle[n_triggers] has_element:Default<KeyType, bool>; // is entry present ?
       port bundle[n_triggers] get_element:Default<KeyType, ElementType>; // get element for given key
       port bundle[n_triggers] remove:Default<KeyType, ElementType>;
       port bundle[n_triggers] update_element:Default<KeyType, ElementType>;
       port bundle[n_triggers] update_key:Default<ElementType, KeyType>;
    
       reaction(add.in) -> add.out {=
         // Reaction Logic
       =}
    }
    

Each of the port bundle here in this example is based on perfect request/response pattern

For cases like this, which in fact is the most common case Inheritance cannot work simply because this is
out of the scope for Inheritance. In this example I'm using combinations of same KeyType and ElementType but in most
of our components we even use types which are internal.

---

Proposed Syntax

Before bundle

reactor Server {
    input request:int;
    output response:float;

    reaction(request) -> response {=
        float t = request->value * 3.1415;
        lf_set(response, t);
    =}
}

reactor Client {
    output request:int;
    input response:float;

    timer t(0, 2sec);
    reaction(t) -> request {=
        lf_set(request, rand());
    =}

    reaction(response) {=
        printf("Got %f \n", response->value);
    =}
}

main reactor {
    s = new Server();
    c = new Client();

    c.request -> s.request;
    s.response -> c.response;
}

---

After bundle

bundle Default<T1, T2> {
    input request:T1;
    output response:T2;
}

reactor Server {
    port bundle com:Default<int, float>; // This is the consumer

    reaction(com.request) -> com.response {=
        float t = com.in->value * 3.1415;
        lf_set(com.response, t);
    =}
}

reactor Client {
    timer t(0, 2sec);

    port bundle com:Mirrored(Default<int, float>); // This is the initiator
    reaction(t) -> com.request {=
        lf_set(com.request, rand());
    =}

    reaction(com.response) {=
        printf("Got %f \n", com.response->value);
    =}
}

main reactor {
    s = new Server();
    c = new Client();


    s.com <-> c.com; // This is a perfect req-resp; the diagram will only show One bi-direectional arrow
}

Multiport Bundles

The multi-port implementation for bundle can follow one of the following approaches:

• It can follow the semantics of banks

  • bundle Default<T1, T2> {
      input in:T1;
      output out:T2;
    }
    reactor A {
      port bundle[10] comm:Default<int, float>;
      reaction(comm.in) -> comm.out {=
          for (int i = 0; i < comm_width; ++i) {
              if (comm[i]->in->is_present) {
                  lf_set(comm[i]->out, comm[i]->in->value * 3.1415);
              }
          }
      =}
    }
    

• We can pass the width as a parameter to the bundle like

  • bundle Default<T1, T2>(n_width:int = 1) {
      input[n_width] in:T1;
      output[n_width] out:T2;
    }
    reactor A {
      port bundle comm:Default<int, float>(n_width = 10);
      reactor(comm.in) -> comm.out {=
          for (int i = 0; i < comm.in_width; ++i) {
              if (comm.in[i]->is_present) {
                  lf_set(comm.out[i], comm.in[i]->value * 3.1415);
              }
          }
      =}
    }
    

• We can do pass the width implicitly to the bundle's input and output port from instantiation like:

  • bundle Default<T1, T2> {
      input in:T1;
      output out:T2;
    }
    reactor A {
      port bundle[10] comm:Default<int, float>; // This will implicitly make the input output ports of bundle with a width of 10 
      reaction(comm.in) -> comm.out {=
          for (int i = 0; i < com.in_width; ++i) {
              if (comm.in[i]->is_present) {
                  lf_set(comm.out[i], comm.in[i]->value * 3.1415);
              }
          }
      =}
    }
    
    

---

Visual Changes

Before

After

---

[edwardalee]

I don't understand why this isn't more easily and clearly addressed using inheritance plus a change in the diagram layout that would allow input ports on the right.

[mkhubaibumer]

@edwardalee one reason of that is, that a component can have multiple request/response pairs (bundles if you will)
In case of Inheritance that doesn't work in a re-useable fashion.

Even a simple generic bundle with single input single output can be declared n-times in a reactor with different names for n-components

[edwardalee]

Wouldn't a base class with parameterized multiports accomplish this?

[mkhubaibumer]

@edwardalee I have update the discussion with reason as to why Inheritance won't work in this case. Please let me know if you need further examples for the specified pattern.

[edwardalee]

The hashtable access example looks a bit awkward to me. Wouldn't it be better to just have one connection and include in the struct that you send to the hashtable an enum specifying the command (add, has_element, get_element, remove, update_element, or update_key)? The response could similarly be a struct where fields suitable to the response are set.

In any case, I get your point that the bundle syntax could, in some circumstances, make a specification more concise. But I feel that any addition to syntax comes with considerable costs: It complicates documentation and tutorials, creating higher barriers to entry; it complicates subsequent innovation (e.g., the bundles will need to be supported in federated execution); and it opens up potential confusion by giving multiple ways to achieve the same thing. I am not convinced that this particular syntax change is worth these costs.

To be clear, we can leave this open, but Berkeley does not have the resources right now to address this. We have too many other priorities in the works. I'm OK with it if someone else picks this up.

[a-sr]

@mkhubaibumer Yes, this would technically be possible but you have to catch this specific case in the synthesis and configure the diagram accordingly. However, in my opinion, your proposed arrangement breaks with some conventions (in terms of directional flow and I/O indications, e.g. the reaction flags) established in LF diagrams. Hence, I would recommend a careful consideration before implemented such a solution.

[soerendomroes]

@mkhubaibumer Yes, but you have to enforce a static order on all ports (which you have to calculate yourself), which is for many models not desired.

[mkhubaibumer]

@soerendomroes can you point me to the docs on how to enforce the static order or maybe a route to get there?

[mkhubaibumer]

@a-sr we have use cases where even a rather simple network of 10-15 entities/components can make the diagrams totally incomprehensible. The interesting thing is most of these connections follow a request/response strategy in most cases.
That's why we are thinking about this optional rendering way to merge the request and response ports with single bidirectional arrow. We are thinking to use the annotations @tuple("value") to hint which ports constitutes a request/response pair.

Do you have any suggestions in this regard?

[soerendomroes]

@mkhubaibumer You can find the documentation for portConstraints here and here is an example how to use them.

[petervdonovan]

I talked to @mkhubaibumer, @OmerMajNition, and Andy this morning and it sounds like Magnition may be able to implement this, as long as they are able to ask for feedback so that they do not go down the wrong track and so that they have some assurance that their changes can be merged when they are complete.

I can imagine a few possible scenarios for how this would work. None of these should cause backwards-incompatible changes.

I think I have a personal preference for scenario 1. If scenario 1 is done correctly, I think that it will not affect or increase the complexity of other parts of the code base and will not require very much maintenance overhead after being implemented. Given that this is not a feature that the team at Berkeley is able to invest a substantial amount of resources into, I think it is good to choose an option that is reasonably self-contained and that eliminates bundles from the version of the AST that most of the code base (excluding the validator) operates on.

I also like scenario 1 because I am not pleased about the prospect of making more awkward changes in order to accommodate a particular usage of C syntax. I think that such changes will not translate well to other languages that we might want to use with the C runtime.

Scenario 1: Transform just to regular ports; use port aliases or magic characters such as underscores

Implementation

• Fix the grammar rules and the validator to account for port bundles.
• If using port aliases rather than underscores, add a validator check that ensures that whenever a bundled port is referenced, an alias is given.
• Use an AST transformation to do the following:
  • Traverse the AST (not the ReactorInstance graph, and without necessarily using any of the TypeParameterizedReactor infrastructure) and convert all bundled ports into regular ports that have mangled names. This does not require substituting in any concrete types for type parameters that are not available in the containing reactor; the concrete types will be substituted in later by the generics implementation downstream.
  • In all places where bundled ports were referenced, replace the bundled port references to the corresponding mangled names, but make the names accessible to the user using the aliases they provided (or names that use underscores in place of dot access notation) so that they do not need to work with mangled names.
• Register the AST transformation with GeneratorBase. Possibly also call into it in FedGenerator, before the FedGenerator does any manipulations on the AST.

Estimated time: 2-6 weeks

Disadvantages

• port aliases are a controversial subject; however, if you would like to factor reaction bodies out of LF code (which may be necessary in order to be truly polyglot), then you should use port aliases anyway.
• substitution of underscores in place of dot access notation could be confusing to many users

Advantages

• easiest to implement

Scenario 2: Transform just to regular ports; do not use port aliases

Similar to scenario 1. Instead of requiring the implementation of port aliases, this would require invasive changes in the C generator. These invasive changes would touch the CReactionGenerator and would also require some way of passing around information about which ports are generated from bundles. Perhaps these invasive changes would take 1-6 weeks to implement (not including the amount of time to implement most of the same changes as in scenario 1) and would then be part of the maintenance burden for as long as the CGenerator is in use.

Disadvantages

• Harder to predict how much time this would take
• This would create a maintenance burden on the people who work on the C generator

Advantages

• Remains as faithful as possible to current LF syntax

Scenario 3: Transform just to regular ports; do an AST transformation on reaction bodies that transforms dot access notation into magic characters such as underscores

Implementation

Same as for scenario 1 with magic characters such as underscores, but with an additional step in the AST transformation that transforms the C reaction bodies as needed.

This additional step would take maybe 20 minutes to implement incorrectly. An incorrect implementation that just does a simple regex replacement would be sufficient to try the feature on test programs. In the long run it would likely be necessary to fully parse the C code, which is feasible. There exist publicly available C parsers.

Estimated time: Same amount of time as scenario 1 to implement incorrectly; unknown (maybe 2-6 additional weeks) to implement correctly

Disadvantages

• This would increase the amount of technical debt and bugs in the CGenerator for the foreseeable future until the feature is deemed important enough to implement correctly

Advantages

• Easy to implement incorrectly
• Remains as faithful as possible to the current LF syntax

Scenario 4: Use reactors in addition to creating regular ports for bundles

Implementation

• Fix the grammar and validator to accept bundles, as in the first step of Scenario 1.
• Use an AST transformation to do the following:
  • Replace bundled ports with regular ports, as in Scenario 1.
  • Convert bundle definitions into (possibly generic) reactor class definitions.
  • Connect the reactor classes to the newly created ports. Note that this will require some mangling of the names of the ports that are not directly accessed by reactions.
  • Ensure that the reactions and connections that used to reference the bundled ports now reference the ports of the reactor instance that exists in place of the bundle.
• Somehow (how?) address the problem that sometimes two dot accesses will appear in the same expression (when referencing the bundled port of a contained reactor)
• Register the AST transformation as in Scenario 1.

Estimated time: 4-8 weeks, but possibly more depending on how we address the problem that sometimes two dot accesses appear in the the same expression.

Probably that problem would have to be resolved using some of the same methods as in Scenarios 1-3.

Disadvantages:

• Does not really solve the dot access problem
• Moderately complex, but at least not an invasive change

Advantages:

• Preserves some (but not all) of the existing C syntax that is currently used within reaction bodies.

[petervdonovan]

In the above post I never considered the updates that would be required in the diagrams code. I have never worked with the diagrams code, so I might not be the person to ask in order to figure out how long it would take to modify it.

[cmnrd]

Independent of how this could be implemented, I do like the syntax proposal! I have the feeling that bundle might not be the clearest keyword, but I also cannot think of a better alternative right now. I have a few questions though:

• What exactly does the <-> operator do? Is it a bi-directional connection operator that only works for bundles with both inputs and outputs? Or is it a more general bundle connection operator where I can also connect a bundle of only outputs?

• I also don't quite understand yet how directionality works here. In your example you define one bundle and then both server and client use the same bundle in their ports. But how does the client know that request is actually an output in its context and the server that request is an input?

[mkhubaibumer]

The reason for that is auto-inferring which input goes to which output of a bundle.

bundle Custom<T1, T2> {
    input in:T1;
    output out:T2
}
reactor A {
    port bndl:Custom<int, float>;
    ...
}
reactor B {
    port bndl:Mirrored(Custom<int, float>);
    ...
}

If we have multiple inputs or outputs a.bndl <-> b.bndl will not make sense as we will not be able to infer which input goes to which output.

[lhstrh]

The reason for that is auto-inferring which input goes to which output of a bundle.

bundle Custom<T1, T2> {
    input in:T1;
    output out:T2
}
reactor A {
    port bndl:Custom<int, float>;
    ...
}
reactor B {
    port bndl:Mirrored(Custom<int, float>);
    ...
}

If we have multiple inputs or outputs a.bndl <-> b.bndl will not make sense as we will not be able to infer which input goes to which output.

There are ways in which it could make sense. For instance, by doing a positional matching and/or type matching...

[khubaibumer]

@lhstrh I think positional matching would be more appropriate as there can be multiple ports with similar types.
However, we still might enforce these limitations for <-> operator just to limit scope of this feature for initial release.

[petervdonovan]

FWIW, Chisel solves this problem by doing name-matching. However, I agree with Khubaib that for the purpose of getting a first implementation done and trying it out, it is good to just go ahead with a version that has these limitations.

[cmnrd]

I kind of understand the bundle as a type. If we only allow bundles of the same type to be connected, then I don't see an issue.