I’m starting to have a look at the file API (in order to use it for Kate), and some questions came up.
Shared vs. client queries: when should I use which ? A client query seems to make sense to me, but what would actually speak against using a shared query ?
If using a client query, would a unique name per application (e.g. “kate”) be good enough, or would you recommend a unique name per application instance (e.g. “kate-<pid>”) ?
I could also check, before actually writing a query file and running cmake, whether there are already reply files there and just read them. Would that be a good idea ?
I was a bit surprised not to see the name used in a client-query in the replies, I expected to see the client name as part of the reply filenames or to find the reply files for a client in a subdir for that client, or something like this. Am I right that there is no way to really see whether the reply files belong to “my” client ?
Stateful queries: why would I want to use those, why would I want to get different versions ?
You own a client query, no-one owns a shared query. You can safely modify or remove a client query at any time, since you own it. The same guarantee doesn’t apply to a shared query. Once a shared query is created, technically you should never programmatically modify or remove it. Only the user should do that manually.
A unique name per application would normally be what you’d use. It would be a bit strange if different instances of an application needed different queries. And if you made each query PID-specific, you’d be left with the problem of who should clean up those queries if the application crashes?
No don’t do that. If you require specific data to be available in the replies, make a query that ensures that data will be there.
There isn’t a one-to-one mapping of replies to queries. The reply contains a merged set of all things requested by all the queries. Data from stateful queries is present in the replies index, not as separate replies. No client “owns” the reply files, CMake owns them. Note that even the project itself can submit an API request directly as of CMake 3.27, and in that case, there is no query file.
I can’t help you here. I’ve never used a stateful query, nor encountered a scenario that needed one. I’m sure there are cases where they are helpful, I just have no experience with them.
Since you mentioned “cleaning up the files”, which files and at which point in time should the application delete ?
Or can I just leave the query files where they are, so on all following cmake runs cmake will generate fresh reply files. So when I check the next time, and my query files are still there, then also the reply files, if they exist, should be up to date, right ?
Practically, your application probably never needs to delete its own queries. You can most likely leave them behind and either the user will delete them when they delete their build directory, or they will sit there doing little harm. At worst, CMake will do a bit more work than it needs to at the end of its generation step, but the run time cost of that should be negligible.
You may want to check the time stamps of the application’s query file(s) against the time stamp of the replies (maybe just against the reply index file is enough). That should tell if you CMake has run since you last modified your query file.
