This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new e88cb46 docs(format): remove doxygen content (#140)
e88cb46 is described below
commit e88cb46419220786d54887f1b7a2fa086d6a0c30
Author: David Li <[email protected]>
AuthorDate: Fri Sep 23 10:48:34 2022 -0400
docs(format): remove doxygen content (#140)
The content will be added to the docs instead.
---
adbc.h | 198 +++--------------------------------------------------------------
1 file changed, 7 insertions(+), 191 deletions(-)
diff --git a/adbc.h b/adbc.h
index cda53a6..31331ae 100644
--- a/adbc.h
+++ b/adbc.h
@@ -28,6 +28,13 @@
/// provided, which implements this same API, but dynamically loads
/// drivers internally and forwards calls appropriately.
///
+/// ADBC uses structs with free functions that operate on those
+/// structs to model objects.
+///
+/// In general, objects allow serialized access from multiple threads,
+/// but not concurrent access. Specific implementations may permit
+/// multiple threads.
+///
/// \version 1.0.0
#pragma once
@@ -156,15 +163,6 @@ struct ArrowArrayStream {
#endif // defined(_WIN32)
#endif // !defined(ADBC_EXPORT)
-/// \page object-model Object Model
-///
-/// ADBC uses structs with free functions that operate on those
-/// structs to model objects.
-///
-/// In general, objects allow serialized access from multiple threads,
-/// but not concurrent access. Specific implementations may permit
-/// multiple threads.
-
// Forward declarations
struct AdbcDriver;
struct AdbcStatement;
@@ -1129,185 +1127,3 @@ typedef AdbcStatusCode (*AdbcDriverInitFunc)(int
version, void* driver,
#ifdef __cplusplus
}
#endif
-
-/// \page decoder-ring Comparison with Other APIs
-///
-/// <table>
-/// <caption>Equivalent concepts between ADBC and other APIs</caption>
-/// <tr>
-/// <th>Concept/API </th>
-/// <th>ADBC </th>
-/// <th>database/sql (Golang) </th>
-/// <th>DBAPI 2.0 (PEP 249) </th>
-/// <th>Flight SQL </th>
-/// <th>JDBC </th>
-/// <th>ODBC </th>
-/// </tr>
-/// <tr>
-/// <td>Shared connection state </td>
-/// <td>AdbcDatabase </td>
-/// <td>DB </td>
-/// <td>- </td>
-/// <td>- </td>
-/// <td>- </td>
-/// <td>- </td>
-/// </tr>
-/// <tr>
-/// <td>Database connection </td>
-/// <td>AdbcConnection </td>
-/// <td>Conn </td>
-/// <td>Connection </td>
-/// <td>FlightSqlClient </td>
-/// <td>Connection </td>
-/// <td>SQLHANDLE (connection) </td>
-/// </tr>
-/// <tr>
-/// <td>Query state </td>
-/// <td>AdbcStatement </td>
-/// <td>- </td>
-/// <td>Cursor </td>
-/// <td>- </td>
-/// <td>Statement </td>
-/// <td>SQLHANDLE (statement) </td>
-/// </tr>
-/// <tr>
-/// <td>Prepared statement handle</td>
-/// <td>AdbcStatement </td>
-/// <td>Stmt </td>
-/// <td>Cursor </td>
-/// <td>PreparedStatement </td>
-/// <td>PreparedStatement </td>
-/// <td>SQLHANDLE (statement) </td>
-/// </tr>
-/// <tr>
-/// <td>Result set </td>
-/// <td>ArrowArrayStream </td>
-/// <td>*Rows </td>
-/// <td>Cursor </td>
-/// <td>FlightInfo </td>
-/// <td>ResultSet </td>
-/// <td>SQLHANDLE (statement) </td>
-/// </tr>
-/// </table>
-
-/// \page compatibility Backwards and Forwards Compatibility
-///
-/// ## Compatibility
-///
-/// The goal is to be **ABI-compatible** across releases. Hence, a
-/// few choices were made:
-///
-/// - Most structures do not contain embedded fields or functions, but
-/// instead use free functions, making it easy to add new functions.
-/// - Enumerations are defined via `typedef`/`#define`.
-///
-/// Of course, we can never add/remove/change struct members, and we
-/// can never change the signatures of existing functions.
-///
-/// The main point of concern is compatibility of AdbcDriver.
-///
-/// The driver entrypoint, AdbcDriverInitFunc(), is given a version
-/// and a pointer to a table of function pointers to initialize. The
-/// type of the table will depend on the version; when a new version
-/// of ADBC is accepted, then a new table of function pointers will be
-/// added. That way, the driver knows the type of the table. If/when
-/// we add a new ADBC version, the following scenarios are possible:
-///
-/// - An updated client application uses an old driver library. The
-/// client will pass a `version` field greater than what the driver
-/// recognizes, so the driver will return ADBC_STATUS_NOT_IMPLEMENTED
-/// and the client can decide whether to abort or retry with an older
-/// version.
-/// - An old client application uses an updated driver library. The
-/// client will pass a `version` lower than what the driver
-/// recognizes, so the driver can either error, or if it can still
-/// implement the old API contract, initialize the older table.
-///
-/// This approach does not let us change the signatures of existing
-/// functions, but we can add new functions and remove existing ones.
-///
-/// ## Versioning
-///
-/// ADBC is versioned separately from the core Arrow project. The API
-/// standard and components (driver manager, drivers) are also
-/// versioned separately, but both follow semantic versioning.
-///
-/// For example: components may make backwards-compatible releases as
-/// 1.0.0, 1.0.1, 1.1.0, 1.2.0, etc. They may release
-/// backwards-incompatible versions such as 2.0.0, but which still
-/// implement the API standard version 1.0.0.
-///
-/// Similarly, this documentation describes the ADBC API standard
-/// version 1.0.0. If/when a compatible revision is made (e.g. new
-/// standard options are defined), the next version would be 1.1.0.
-/// If incompatible changes are made (e.g. new API functions), the
-/// next version would be 2.0.0.
-
-/// \page concurrency Concurrency and Thread Safety
-///
-/// In general, objects allow serialized access from multiple threads:
-/// one thread may make a call, and once finished, another thread may
-/// make a call. They do not allow concurrent access from multiple
-/// threads.
-///
-/// Somewhat related is the question of overlapping/concurrent
-/// execution of multi-step operations, from a single thread or
-/// multiple threads. For example, two AdbcStatement objects can be
-/// created from the same AdbcConnection:
-///
-/// ```c
-/// struct AdbcStatement stmt1;
-/// struct AdbcStatement stmt2;
-///
-/// // Ignoring error handling for brevity
-/// AdbcStatementNew(&conn, &stmt1, NULL);
-/// AdbcStatementNew(&conn, &stmt2, NULL);
-/// AdbcStatementSetSqlQuery(&stmt1, "SELECT * FROM a", NULL);
-/// AdbcStatementSetSqlQuery(&stmt2, "SELECT * FROM b", NULL);
-///
-/// AdbcStatementExecute(&stmt1, NULL);
-/// AdbcStatementExecute(&stmt2, NULL);
-/// // What happens to the result set of stmt1?
-/// ```
-///
-/// What happens if the client application calls
-/// `AdbcStatementExecute` on `stmt1`, then on `stmt2`, without
-/// reading the result set of `stmt1`? Some existing client
-/// libraries/protocols, like libpq, don't support concurrent
-/// execution of queries from a single connection. So the driver
-/// would have to either 1) buffer all results into memory during the
-/// first `Execute` 2) issue an error on the second `Execute`, or 3)
-/// invalidate the first statement's result set on the second
-/// `Execute`.
-///
-/// In this case, ADBC allows drivers to choose 1) or 2). If possible
-/// and reasonable, the driver should allow concurrent execution,
-/// whether because the underlying protocol is designed for it or by
-/// buffering result sets. But the driver is allowed to error if it
-/// is not possible to support it.
-///
-/// Another use case is having a single statement, but executing it
-/// multiple times and reading the result sets concurrently. A client
-/// might desire to do this with a prepared statement, for instance:
-///
-/// ```c
-/// // Ignoring error handling for brevity
-/// struct AdbcStatement stmt;
-/// AdbcStatementNew(&conn, &stmt, NULL);
-/// AdbcStatementSetSqlQuery(&stmt, "SELECT * FROM a WHERE foo > ?", NULL);
-/// AdbcStatementPrepare(&stmt, NULL);
-///
-/// AdbcStatementBind(&stmt, &array1, &schema, NULL);
-/// AdbcStatementExecute(&stmt, NULL);
-/// AdbcStatementGetStream(&stmt, &stream, NULL);
-/// // Spawn a thread to process `stream`
-///
-/// AdbcStatementBind(&stmt, &array2, &schema, NULL);
-/// AdbcStatementExecute(&stmt, NULL);
-/// // What happens to `stream` here?
-/// ```
-///
-/// ADBC chooses to disallow this (specifically: the second call to
-/// `Execute` must invalidate the result set of the first call),
-/// because generally, existing APIs do not support 'overlapping'
-/// usage of a single prepared statement in this way.
