lidavidm commented on code in PR #3871:
URL: https://github.com/apache/arrow-adbc/pull/3871#discussion_r2780195743
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -973,6 +991,111 @@ struct AdbcPartitions {
/// @}
+/// \defgroup adbc-statement-multi Multiple Result Set Execution
+/// Some databases support executing a statement that returns multiple
+/// result sets. This section defines the API for working with such
+/// statements and result sets.
+/// @{
+
+/// \brief A struct for handling a potentially multi-result set execution
+///
+/// This struct is populated by AdbcStatementExecuteMulti and can be used to
iterate
+/// through the result sets of the execution. The caller can use the
NextResultSet or
+/// NextResultSetPartitions functions on the AdbcMultiResultSet struct to
iterate through
+/// the result sets. The caller is responsible for calling the release
function when
+/// finished with the result set.
+///
+/// \since ADBC API revision 1.2.0
+struct ADBC_EXPORT AdbcMultiResultSet {
+ /// \brief opaque implementation-defined state
+ void* private_data;
+
+ /// \brief The associated driver
+ struct AdbcDriver* private_driver;
+};
+
+/// \brief Release the AdbcMultiResultSet and any associated resources.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// If all the result sets have not been completely consumed, then the driver
+/// should cancel any remaining work if this is called.
+///
+/// \param[in] result_set The result set to release.
+/// \param[out] error An optional location to return an error message if
necessary.
+///
+/// \return ADBC_STATUS_OK on success or an appropriate error code.
+AdbcStatusCode AdbcResultSetRelease(struct AdbcMultiResultSet* result_set,
+ struct AdbcError* error);
Review Comment:
And `MultiResultSetNext`, etc, agreed
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1135,6 +1261,40 @@ struct ADBC_EXPORT AdbcDriver {
struct AdbcError*);
/// @}
+
+ /// \defgroup adbc-1.2.0 ADBC API Revision 1.2.0
+ ///
+ /// Functions added in ADBC 1.2.0. For backwards compatibility,
+ /// these members must not be accessed unless the version passed to
+ /// the AdbcDriverInitFunc is greater than or equal to
+ /// ADBC_VERSION_1_2_0.
+ ///
+ /// When a driver implementing an older spec is loaded by a newer
+ /// driver manager, the newer manager will allocate the new, expanded
+ /// AdbcDriver struct and attempt to have the driver initialize it with
+ /// the newer version. This must return an error, after which the driver
+ /// will try again with successively older versions all the way back to
+ /// ADBC_VERSION_1_0_0. The driver must not access the new fields,
+ /// which will carry undefined values.
Review Comment:
Probably we should describe the user perspective and driver perspective
separately.
From the user perspective: the manager will return a fully populated struct,
but some of the functions may fail with NOT_IMPLEMENTED.
From the driver perspective: they should not access members outside of the
version specified by the driver manager. (Though this is already required by
the contract on the init func, and also you have no other way of knowing the
size of the struct, nor do you know whether it's the driver manager or
something else calling you.) I don't think we need to specify what exactly the
driver manager does here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
