Document life cycle of data returned by various C APIs better

[ray6080]

This is a suggestion made by Capn Core Dump from our discord thread (https://discord.com/channels/1196510116388806837/1414242474632806410/1414247214569750620). The documentation of lifecycles can make the life of our C API users easier.

Examples are:

• QueryResult returned from queries with single query statement.
• Multi QueryResults chained returned from queries with multi query statements.
• FlatTuple
• Connection
• ...

[dtenny]

This would be great! Add char* results to the list as well for all the to_string and as_string APIs.

As I near completion of the Lisp API, the biggest questions that have dogged me in its development were:

1. Whether I should call kuzu-destroy-xxx on the returned data. I believe the answer is always, but it took me a while to convince myself, and there are the trickier situations such as a query that has multiple query results as per discord discussion.

2. What sorts of data lifetime limits apply to the returned data. Whether kuzu_flat_tuples can still be used if the kuzu_query_result is destroyed, or whether the char* from kuzu_query_result_to_string can be used after the kuzu_query_result is destroyed.

So basically questions of ownership (responsibility to destroy) and lifetime for all returned data.

The model I've followed is to require scoping such that database->connection->query-result->tuple->values relationships define the lifetime of data unless I have copied it. That seems simple, but even then, say you're looking at kuzu_values of one kuzu_flat_tuple, does it mean kuzu_values derived from the previous kuzu_flat_tuple in the sequence are no longer valid?

API developers want to know :-).

[dtenny]

On the ownership thing, it might be good to advise people on when they need to set is_owned_by_cpp to true when they supply user-allocated kuzu structures for use. I believe the only time I've needed it was when I allocated a kuzu_value structure for some calls. I understand from what Guodong Jin said that the C API was originally for internal use. From an outside perspective understanding this stuff is pretty important for all the folks using the C API to implement other language bindings. Failure to understand it means buggy bindings.

Also, at least one of the C APIs would only partially set the state of an input-output structure in certain
circumstances, so initializing them to zero before sending them to the C API to be filled in is advised.
(I don't remember which API it was but I can probably find it if anybody cares) .

Anyway, thanks for the support, good stuff.