[Discussion] API to associate binding state (pointers) with the JerryScript context

[martijnthe]

A while ago, JERRY_CONTEXT define and jerry_context_t had been added.
Before that change, all the fields in jerry_context_t were statics that were sprinkled throughout the JerryScript code base. This wasn't great for projects where multiple instances of JerryScript are needed, because statics are by definition "singleton".

Luckily, the addition of the JERRY_CONTEXT define made it easier to create multiple instances of JerryScript. Typically, to support multiple instances, one would provide a custom definition of JERRY_CONTEXT, for example to look up the current jerry_context_t in thread local storage.

However, often, binding code also needs to keep state regarding the native resources that it uses. In a multi-context scenario, each instance of JerryScript needs to have its own "instance" of this binding state as well. Therefore, using static variables cannot be used. Again, because static equals "singleton".

Using __thread or a platform-specific thread local storage (TLS) API could be used of course, but this would make the binding code less portable / re-usable.

Therefore, I think it make sense to try to come up with an API to associate binding state with a JerryScript context in an easy way that promotes re-use and portability of the binding code.

Some design goals that I have in mind for this an API to associate binding state with a JerryScript context:

• enable multiple bindings to each associate their own state with a JerryScript context.
• making binding code "portable" / re-usable: avoid __thread or a platform specific TLS API.
• should not require having to change JerryScript code (incl. jcontext.[h|c]).
• "scales down": no bloat when using a single-context (same speed/RAM/code size as today).
• easy to use from a developer point of view (probably not as easy as static, but hopefully close?)

I imagining something like a void *user_binding_state[] array in JERRY_CONTEXT, plus a couple of jerry_... functions to register/allocate/get/free the state for a particular binding. But I'm not quite sure how such a solution would "scale down".

Thoughts?

[martijnthe]

cc @jiangzidong @zherczeg ideas?

[zherczeg]

What about adding two functions: one for setting a global user pointer and another to getting this pointer?

[martijnthe]

What about adding two functions: one for setting a global user pointer and another to getting this pointer?

That would mean you'd have to put all the pieces of state from various bindings into one big struct: not great for keeping the various bindings modular.
Or have some custom mechanism on top of the single user pointer to "mux" the single global one into a separate pointer per binding module: also not great, because everyone would implement their own mechanism for this over and over and bindings would not be easily reusable across projects (unless we magically all implement the exact same thing).

I added a "design goal" to the list: enable multiple bindings to each associate their own state with a JerryScript context.

[jiangzidong]

About "scale down":
IMO, we don't need the perfect "scale down"
It's ok to add a pointer member in the jerry_context_t, and the pointer points to a struct/array which contains binding states. Then the memory for each jerry context increases sizeof(void *), which should be acceptable.

[jiangzidong]

@martijnthe

because everyone would implement their own mechanism for this over and over and bindings would not be easily reusable across projects

It's hard to implement a general binding state struct/array so that we can reuse other binding codes directly, because binding scenarios are various.
@zherczeg 's method, binding-writer should define what's the pointer points to. A struct or array, totally up to the binding-writer.
@martijnthe 's array method, binding-write should also define the length of the array, and meanings of index.

[zherczeg]

As for me I would offer such things as an option. From JerryScript core side it would only be a pointer, but there would be utilities which offer more, and people could select what fits their use case. I described this concept in #1716.

[gabrielschulhof]

You have to also consider that there may be multiple mutually exclusive uses for adding a pointer to the context. For example, V8's isolate has SetData() and the corresponding GetData(), but when we were implementing N-API we wanted to tack binding-specific data onto the Isolate using those APIs but we couldn't, because there are other native modules out there that also do that, making use of one of the four slots.

So, if you're a binding and you retrieve the pointer from the context, is this the pointer you set, or is this the pointer some other binding set, because its init ran before your init?

Fortunately, we're dealing with a JavaScript engine here, right? So, we could create an object that is not exposed to JavaScript and attach it to the context, and then various bindings could claim various property keys on the object and attach their data as the value.

So, like

#define MY_BINDING_DATA_KEY "my_binding_data_key"
...
my_binding_data *my_data = get_my_binding_data();
jerry_value_t context_object = jerry_get_context_object(context);
jerry_value_t my_property_value = jerry_create_object();
jerry_set_object_native_handle(my_property_value, (uintptr_t)my_data, free_my_binding_data);
jerry_value_t prop_name = jerry_create_string_from_utf8(MY_BINDING_DATA_KEY);
jerry_set_property(context_object, prop_name, my_property_value);
...

Basically, I wish to caution that a single pointer is insufficient because there may be multiple independent reasons for attaching data to a context. Thus, we should be exploiting the fact that JavaScript objects are string-keyed hashes.

The example above could be made more efficient with a custom API, of course. After all, we do not need entire JS objects hanging from the one context object, but only native pointers. The important thing IMO is that the pointers are stored in a string-keyed hash, though.

[gabrielschulhof]

For reference: nodejs/abi-stable-node#206 (comment)

[gabrielschulhof]

Basically, we ended up going with a per-module context, allocated when the module is first initialized, and then stored in the context for all native callbacks. This has the following downside: nodejs/node#12246 (review)

[gabrielschulhof]

Another nice benefit of implementing the JS external-data-plus-deleter approach is that, when a context is discarded, the deleters associated with the data will also be called, and so the bindings will be informed that a certain context has been discarded. This is also missing in V8.

[zherczeg]

Hm, what about reversing the question? Instead allowing setting pointers in JerryScript context, we could retrieve the starting address of the context, which should be unique. This could be a key to access various local properties.

[gabrielschulhof]

So have a context-keyed hash stored statically and globally in the binding, right? That's also possible, of course, as long as there is one well-known, well-documented key that can be used. Currently it sounds like the jerry_context_t* is that key.

[gabrielschulhof]

Then the binding won't know that a context has been discarded though and so it won't know that it can delete a key from the hash. There should be a callback to inform about that.

[gabrielschulhof]

Also it might be real nice if bindings didn't have to implement their own hash table, because five different bindings will implement it five different ways.

[gabrielschulhof]

It just ends up being boilerplate.