s/context/\0ifiedSandbox/

structured cloning isn't a thing any more (https://html.spec.whatwg.org/multipage/structured-data.html#structuredclone).

Heh. Right. I think this is still what it’s known as, though? (That it’s implemented as a serialize + deserialize step should be more or less transparent to users)

@addaleax That article is pretty outdated though (it has no mention of MessagePort or SharedArrayBuffer)... HTML structured serialization/deserialization? maybe a link to v8.Serializer/Deserializer?

(it has no mention of MessagePort or SharedArrayBuffer)

That’s why these are mentioned explicitly here ;)

maybe a link to v8.Serializer/Deserializer?

Yeah, that’s a good idea … that should give people an idea of how to play around with the algorithm without spinning up message channels every time. I’ve added:

+For more information on the serialization and deserialization mechanisms
+behind this API, see the [serialization API of the `v8` module][v8.serdes].

Ayo or Ayo.js.

Is Worker available in a worker?

Is Worker available in a worker?

Yes. That’s also tested and the code is generally laid out to support such a structure, in part because there’s not really anything standing in the way of it

nit: 'message'

What arguments does this event get? (value, transferList)?

Only value. We could try to add the transferList too, if that seems useful, but all of the relevant objects should be reachable through value anyway.

I don’t know if we have some standard format for saying “this events has one parameter that can be any JS value”, so I’m adding prose for it.

I think something like the following is used. Basically the same format as function parameters.

### Event: 'event'

* `value` {any} The value

This event is fired when ...

Ah, thanks – done!

nit: Cannot

Fixed!

Something I've been thinking is that the messaging API could well be applicable to VM contexts too. Is that a correct understanding?

Yes, that is a correct understanding, because the ports in a channel can be moved to different contexts

Maybe just vm.transferMessagePort()? The "to context" part is already conveyed by the fact that this method is in vm module, and "transfer" is a more Proper(R) name IMO than "move".

What I like about move rather than transfer is that it conveys better that the original message port object is now rendered unusable … I don’t feel strongly about it, though

Aww... ;)

Is GetFunction() cached by context?

Yup – I have to admit I never got the point of {Function,Object}Templates before making this PR. However, in retrospect it’s a lot clearer: It’s a Template in the sense that it can be used to create functionally equivalent functions/objects in different contexts.

Make these private?

I think that would require giving the SerializerDelegate that accesses these a publicly visibly identifier, right?

Ditto.

You mean, refer to cluster here?

No, I intended to refer to the comment of adding parameter types. Seems like github messed up the order :/

Ah – in that case, done :)

I'd add some CHECKs or even mutexes here making sure it's thread-safe, and only works when either port is not entangled.

I think CHECKs for making sure that the ports aren’t entangled are fine. The method isn’t really required or supposed to be thread-safe, I’ve noted that in the documentation. (It’s only called by the thread that created both message ports.)

You can even explicitly call out clusters here.

I would mention message passing as the primary means of communication between the worker thread and the thread that spawned the worker. Maybe something like:

Like [Web Workers] and the [cluster module], two-way communication can be achieved through inter-thread message passing. Internally, a Worker has a built-in pair of [MessagePort]s that are already associated with each other when the Worker is created. While the MessagePort objects are not directly exposed, their functionalities are exposed through [worker.postMessage()] and the ['message' event] on the Worker object for the parent thread, and [require('worker').postMessage()] and the ['workerMessage' event] on require('worker') for the child thread.

To create custom messaging channels (which is strongly encouraged over using the default global channel for more complex tasks), users can create a MessageChannel object on either thread and pass one of the MessagePorts on that MessageChannel to the other thread through a pre-existing channel, such as the global one.

[insert example]

See [port.postMessage()] for more information on how messages are passed, and what kind of JavaScript values can be successfully transported through the thread barrier.

I'd add a description of what MessageChannel is before saying what it has. Maybe:

The MessageChannel class represents an asynchronous messaging channel.

It seems rather crude to have some MessagePorts being EventEmitters, and some not. I understand you are still working on this part, and that the EventEmitter is implemented in JS complicates things. But I'd rather have it all one way or the other.

But I'd rather have it all one way or the other.

Me too. :) But like with the Buffers, it’s just a problem that not all contexts have a concept of EventEmitters … this would require making some internal modules multi-context ready, which I would like to consider out of scope for this PR. :) Also, this is already quite an advanced feature on its own.

s/an asynchronous communications channel/an end(or port?) of a two-way asynchronous communications channel/

I guess one of the main thing that confused me was how transferList was used. So now I understand that objects present in value (no matter how deep) that are also in transferList are transferred, while ordinarily they are cloned. I wasn't aware of the "ordinarily" part.

However, what if transferList has an object that is not present in value? Will it get neutered as well?

I’m adding clarifications for both points, thanks

Also, please document if/when open() and close() need to be called. An example would be best.

It’s hard to come up with examples for these … I’ve added to the start() documentation that it doesn’t need to be used unless moving-between-VM-contexts is used. (And, as you pointed out below, ideally it wouldn’t be necessary at all).

Regarding close() … I’m not entirely sure whether MessagePorts should be unref()ed by default or not. Right now, any MessagePort keeps an event loop open unless explicitly unref()ed or close()ed …

Is the std::move redundant if MessagePort::Detach already returns a std::move'd smart pointer?

Clang complains:

../src/node_messaging.cc:325:28: warning: moving a temporary object prevents copy elision [-Wpessimizing-move]
      msg_->AddMessagePort(std::move(port->Detach()));
                           ^
../src/node_messaging.cc:325:28: note: remove std::move call here
      msg_->AddMessagePort(std::move(port->Detach()));
                           ^~~~~~~~~~              ~

Will fix.

This std::move(port->data_) should be port->Detach().

s/if/is/

Actually the whole wording of this is a bit weird. Not sure what would be a better way to explain that. 🤔

Not sure what would be a better way to explain that. 🤔

Hm, yeah… was this comment helpful in explaining what’s happening?

It makes sense for the most part. The wording of during whose lifetime the reference count if increased by 1 was a bit hard for me to parse though. I suspect someone even less familiar with threading stuff would be even more confused.

This threadId === 0 check exists in a bunch of places. Could just have a getter at process.binding('worker').isMainThread to make it clearer what the checks are doing.