Clarification around clap_plugin_entry init/deinit

[prokopyl]

I am working on cleaning up some rough edges on my Rust Clap wrapper around DSO loading and entry initialization, and reading through the entry.h file again made me question how I initially interpreted it.

The spec says this about clap_plugin_entry.init:

clap/include/clap/entry.h

Line 38 in e292447

// This function must be called first, and can only be called once.

And about clap_plugin_entry.deinit:

clap/include/clap/entry.h

Line 55 in e292447

// No more calls into the DSO must be made after calling deinit().

My initial interpretation was that because init must be called exactly once, and deinit prevents any further calls into the DSO, a host cannot call init again later, which would means that at that point, the plugin's DSO is pretty much useless and can only be "thrown away".

However that doesn't seem to be exactly what the spec says, and I'm wondering if it could be interpreted in a different, way so that init can be called once more after deinit as been called, for instance:

// Host starts up and loads a plugin for the user
entry->init();

// Plugin factory is retrieved, plugin is instantiated and used, etc.

// User decides to not use the plugin for a while, and host wants to free some resources,
// so it decides to unload the whole entry since there is no instance.
entry->deinit();

// A while later, user wants to use the plugin again (or another plugin in the same DSO),
// so the host needs to initialize the entry again.
entry->init();

// And so on...

I can see this interpretation making more sense, since (at least on Linux) a dlclose call does not necessarily deallocate the DSO and make it start "fresh" for another entry init call.

That would mean hosts following my first interpretation would either need to prevent a plugin's DSO to be loaded a second time after it's been deinit'd (pretty sure no one does this), or they'd need to just keep every single DSO's entry point initialized forever until the host's process is killed (and there could be hundreds of DSOs loaded by plugin scanning/discovery, so that seems weird).

However, my second interpretation seems to clash a good bit with the parts of the spec I quoted above, even though it doesn't seem to be explicitly forbidden either.

So I guess my main question is, is my second interpretation allowed?

Also, not completely related but adding to the confusion, the spec marks both init and deinit as being thread-safe:

clap/include/clap/entry.h

Line 34 in e292447

// Every method must be thread-safe.

To me, "thread safe" means that the methods can be called simultaneously from multiple threads, which seems completely at odds with the fact that these can be called only once.

So far I've interpreted it as init and deinit being thread-agnostic instead, i.e. they can be called in any thread (not necessarily [main-thread]), and different threads from one another, but they definitely cannot be called simultaneously with anything from the same DSO, themselves included. However I don't know if there is another, more correct way to interpret that?

Thanks in advance! 🙂

[defiantnerd]

IMHO it is just that these two steps:

• load DSO and call init()

and

• call deinit() and unload DSO

are seen as atomic steps. A host that scans all plugins will unload them all after inspection.
After unloading the DSO the process is in the same state as if the DSO wasn't loaded at all.

Regarding the thread-safe attribute: as a plugin writer you should not make assumptions about which thread calls init() or deinit() (like: "init() is called always called in the GUI thread"). It can be any thread (or probably even different ones).

[prokopyl]

This is also what I think makes the most sense. Thanks for clarifying! 😄

Perhaps I could make a PR to include all of those details more explicitly in the spec?