Flexible composition with bundling.

[rakudrama]

The intention is that the data for the comment is populated by tools

//# functionsCalledOnLoad=xxxx

Some programs are loaded as a concatenated JavaScript file, but each entry point sees a different set of concatenated files, and not necessarily in the same order, even for the same set.
This will require back-propagating the data into comments in the individual files.

This issue is to ensure the design enables this back-propagation.

[marjakh]

The per-function compile hints are concatenable like this:

File foo1.js:

//# functionsCalledOnLoad=data1
function foo1() { ... } // data1 encodes the location of foo1 relative to the comment end

File foo2.js:

//# functionsCalledOnLoad=data2
function foo2() { ... } // data2 encodes the location of foo2 relative to the comment end

And now the concatenated file

//# functionsCalledOnLoad=data1
function foo1() { ... } // data1 encodes the location of foo1 relative to the comment end

//# functionsCalledOnLoad=data2
function foo2() { ... } // data2 encodes the location of foo2 relative to the comment end

has compile hints for both foo1 and foo2.

[marjakh]

Please let me know if this property is enough for your use case. I didn't fully understand "back-propagating the data into comments in the individual files". (Is that about how to construct compile hints for individual files with PGO? Or about how to handle compile hints when processing the JS files?)

[rakudrama]

Please let me know if this property is enough for your use case. I didn't fully understand "back-propagating the data into comments in the individual files". (Is that about how to construct compile hints for individual files with PGO?

Yes, the concatenated file is ephemeral, and exists only as a stream from the server, and the components might never be in the same order twice. If we don't control the server that does this, perhaps the magic comment could have a form that identifies the original file to be updated.

How much of the PGO process can be stateless? i.e. all entities are sufficiently self-describing so that parts of the process (e.g. the concatenated code server) do not need to be aware of the PGO context?

Or about how to handle compile hints when processing the JS files?)

[marjakh]

So, there are two separate things, how to do the instrumentation for generating the PGO data, and how to put the compile hints into the ephemeral concatenated file. This proposal is only about the compile hints, not about the instrumentation. (I'm confused about "the original file to be updated" in the magic comment.)

I'd roughly imagine that instrumentation works like every function should have its own instrumentation which describes which component the belongs to:

function foo() {
  console.log("component-editing-function-foo");
}

and then the PGO tool would gather all compile hints related to each component, and create a compile hint comment for each component:

editing.js:

//# functionsCalledOnLoad=data1
function foo() { ... }

otherComponent.js:

//# functionsCalledOnLoad=data2

and when serving the final JS file, no matter in which order the components are, the concatenated version is a file with valid compile hint comments.

(This assumes that functions which are inside a component will remain the same during the whole process.)

[rakudrama]

The PGO process should not require recompilation to produce different JavaScript.
Since the JavaScript files can come from several different compilers, we should support a workflow that requires zero buy-in from any compiler. It is fine if some tool chain uses a workflow like you suggest, with explicit logging calls, but PGO at the JavaScript level should be something that can work regardless of the tool chain(s) that generated the JavaScript.

V8 knows which functions were compiled. Can that data be surfaced?

This is a sketch of a workflow that works independently from the compilers used to generate the JavaScript code:

• Some opaque set of compilers and hand-written scripts produce 10000 .js files.

• These are served in concatenated bundles with arbitrary selection and ordering of the original files. No part of the system knows which of the original files are in which script or at what position.

• The original files start with placeholder data that identifies the file:

file123.js:

//# functionsCalledOnLoad=tag:file123.js
<code>

You can tell this is a placeholder since : is not valid in base64 encodings.

• V8 records which function positions are compiled in the scripts that it sees (the concatenated scripts).
  The recording might be enabled by a V8 API call in the PGO version of the index.html file.

• At some point the app requests the accumulated position data.

• When the data is requested, the recorded positions are processed as follows:

For each script:
   For each position:
      Search backwards to find a magic comment
      Subtract the recorded position from the position-0 for the comment
      Add this delta to the set for the magic comment.
  For each magic comment:
    Represent the set of deltas from the comment as the base64 string that would identify the positions.
    Add {"tag": "data"} to the result

(Obviously this can be made more efficient)
The result would be an object that maps placeholder tags to the data that should replace the placeholder, e.g.

{"tag:file123.js": "AABX8QQA",
 "tag:file65.js": "",
  etc
}

• This JSON data can be sent to the server or captured in some other way.

• A simple tool can use the result to replace the placeholders with actual data.

• Perhaps several results could be captured and merged (PGO for common user journeys).

• It might be nice if the JSON contained both the script and the tag, In some cases (e.g. without concatenation) the script might be sufficient.

The positions and the sourcemap could be used to generate something that the user can understand, listing which elements of the original program are in the PGO function set. We have found sourcemaps to be 'lossy', so this is just 'informative' and might not be of a high enough quality to generate good magic comment data.

[marjakh]

Thanks for the explanation, that's an interesting idea. It goes beyond the scope of this proposal, but figuring out that problem area is a potential follow-up.