Merge remote-tracking branch 'origin/wl11654' into wl12751-abi-bump

Author: rsomla1

include/mysqlx/xapi.h

@@ -220,7 +220,7 @@ typedef struct mysqlx_client_struct mysqlx_client_t;
   and can be manipulated using related functions.
 
   @see mysqlx_get_session_from_options(), mysqlx_session_options_new(),
-  mysqlx_session_option_set(), mysqlx_free_options().
+  mysqlx_session_option_set(), mysqlx_free().
 */
 
 typedef struct mysqlx_session_options_struct mysqlx_session_options_t;
@@ -267,6 +267,8 @@ typedef struct mysqlx_table_struct mysqlx_table_t;
 
 typedef struct mysqlx_stmt_struct mysqlx_stmt_t;
 
+typedef struct Mysqlx_diag_base mysqlx_object_t;
+
 
 /**
   Type of row handles.
@@ -515,24 +517,25 @@ mysqlx_lock_contention_t;
 
   @param conn_string    connection string
   @param client_opts    client options in the form of a JSON string.
-  @param[out] out_error if error happens during connect the error message
-                        is returned through this parameter
-  @param[out] err_code  if error happens during connect the error code
+  @param[out] error     if error happens during connect the error object
                         is returned through this parameter
 
   @return client handle if client could be created, otherwise NULL
   is returned and the error information is returned through
-  the out_error and err_code output parameters.
+  the error output parameter.
 
   @note The client returned by the function must be properly closed using
         `mysqlx_client_close()`.
 
+  @note If an error object returned through the output parameter it must be
+        freed using `mysqlx_free()`.
+
   @ingroup xapi_sess
 */
 
 PUBLIC_API mysqlx_client_t *
 mysqlx_get_client_from_url(const char *conn_string, const char *client_opts,
-                     char out_error[MYSQLX_MAX_ERROR_LEN], int *err_code);
+                           mysqlx_error_t **error);
 
 
 /**
@@ -568,25 +571,25 @@ mysqlx_get_client_from_url(http://github.com/const%20char%20*conn_string,%20const%20char%20*client_opts,%3C/div%3E%3C/code%3E%3C/div%3E%3C/td%3E%3C/tr%3E%3Ctr%20class=%22diff-line-row%22%3E%3Ctd%20data-grid-cell-id=%22diff-b6658fd3a7ff3e9e86a9e43cc349168f8a65baad705d5788511de6c9e6bd75cc-568-571-0%22%20data-selected=%22false%22%20role=%22gridcell%22%20style=%22background-color:var(--bgColor-default);text-align:center" tabindex="-1" valign="top" class="focusable-grid-cell diff-line-number position-relative diff-line-number-neutral left-side">568
   @param opt  handle to client configuration data
   @param client_opts    client options in the form of a JSON string.
-  @param[out] out_error if error happens during connect the error message
-                        is returned through this parameter
-  @param[out] err_code if error happens during connect the error code
+  @param[out] error     if error happens during connect the error object
                         is returned through this parameter
 
   @return client handle if client could be created, otherwise NULL
   is returned and the error information is returned through
-  the out_error and err_code output parameters.
+  the error output parameter.
 
   @note The client returned by the function must be properly closed using
         `mysqlx_client_close()`.
 
+  @note If an error object returned through the output parameter it must be
+        freed using `mysqlx_free()`.
+
   @ingroup xapi_sess
 */
 
 PUBLIC_API mysqlx_client_t *
 mysqlx_get_client_from_options(mysqlx_session_options_t *opt,
-                               char out_error[MYSQLX_MAX_ERROR_LEN],
-                               int *err_code);
+                               mysqlx_error_t **error);
 
 /**
   Close the client pool and all sessions created by them.
@@ -614,19 +617,16 @@ PUBLIC_API void mysqlx_client_close(mysqlx_client_t *client);
   Create a new session
 
   @param client     client pool to get session from
-  @param[out] out_error if error happens during getting the session handle from
-                        the pool, the error message is returned through this
-                        parameter
-  @param[out] err_code if error happens during getting the session handle from
-                       the pool, the error code is returned through this
-                       parameter
+  @param[out] error if error happens during connect the error object
+                    is returned through this parameter
 
+  @note If an error object returned through the output parameter it must be
+        freed using `mysqlx_free()`.
 */
 
 PUBLIC_API mysqlx_session_t *
-mysqlx_get_session_from_client(mysqlx_client_t *client,
-                               char out_error[MYSQLX_MAX_ERROR_LEN],
-                               int *err_code);
+mysqlx_get_session_from_client(mysqlx_client_t *cli,
+                               mysqlx_error_t **error);
 
 /**
   Create a new session.
@@ -636,26 +636,26 @@ mysqlx_get_session_from_client(mysqlx_client_t *client,
   @param user       user name
   @param password   password
   @param database   default database name
-  @param[out] out_error if error happens during connect the error message
-                    is returned through this parameter
-  @param[out] err_code if error happens during connect the error code
+  @param[out] error if error happens during connect the error object
                     is returned through this parameter
 
   @return session handle if session could be created, otherwise NULL
           is returned and the error information is returned through
-          the out_error and err_code output parameters.
+          output error parameter.
 
   @note The session returned by the function must be properly closed using
         `mysqlx_session_close()`.
   @note This function always establishes connection with SSL enabled
+  @note If an error object returned through the output parameter it must be
+        freed using `mysqlx_free()`.
 
   @ingroup xapi_sess
 */
 
 PUBLIC_API mysqlx_session_t *
 mysqlx_get_session(const char *host, int port, const char *user,
-                     const char *password, const char *database,
-                     char out_error[MYSQLX_MAX_ERROR_LEN], int *err_code);
+                   const char *password, const char *database,
+                   mysqlx_error_t **error);
 
 
 /**
@@ -673,49 +673,48 @@ mysqlx_get_session(const char *host, int port, const char *user,
 
   Specifying `ssl-ca` option implies `ssl-mode=VERIFY_CA`.
 
-  @param conn_string    connection string
-  @param[out] out_error if error happens during connect the error message
-                        is returned through this parameter
-  @param[out] err_code  if error happens during connect the error code
-                        is returned through this parameter
+  @param conn_string  connection string
+  @param[out] error   if error happens during connect the error object
+                      is returned through this parameter
 
   @return session handle if session could be created, otherwise NULL
   is returned and the error information is returned through
-  the out_error and err_code output parameters.
+  the error output parameter.
 
   @note The session returned by the function must be properly closed using
         `mysqlx_session_close()`.
+  @note If an error object returned through the output parameter it must be
+        freed using `mysqlx_free()`.
 
   @ingroup xapi_sess
 */
 
 PUBLIC_API mysqlx_session_t *
 mysqlx_get_session_from_url(const char *conn_string,
-                     char out_error[MYSQLX_MAX_ERROR_LEN], int *err_code);
-
+                            mysqlx_error_t **error);
 
 /**
   Create a session using session configuration data.
 
-  @param opt  handle to session configuration data
-  @param[out] out_error if error happens during connect the error message
-                        is returned through this parameter
-  @param[out] err_code if error happens during connect the error code
-                        is returned through this parameter
+  @param opt        handle to session configuration data
+  @param[out] error if error happens during connect the error object
+                    is returned through this parameter
 
   @return session handle if session could be created, otherwise NULL
   is returned and the error information is returned through
-  the out_error and err_code output parameters.
+  the error output parameter.
 
   @note The session returned by the function must be properly closed using
         `mysqlx_session_close()`.
+  @note If an error object returned through the output parameter it must be
+        freed using `mysqlx_free()`.
 
   @ingroup xapi_sess
 */
 
 PUBLIC_API mysqlx_session_t *
 mysqlx_get_session_from_options(mysqlx_session_options_t *opt,
-                       char out_error[MYSQLX_MAX_ERROR_LEN], int *err_code);
+                                mysqlx_error_t **error);
 
 
 
@@ -1018,7 +1017,7 @@ mysqlx_rollback_to(  mysqlx_session_t *sess, const char *name);
   @return handle to the newly allocated configuration data
 
   @note The allocated object must be eventually freed by
-        `mysqlx_free_options()` to prevent memory leaks
+        `mysqlx_free()` to prevent memory leaks
 
   @ingroup xapi_sess
 */
@@ -1032,6 +1031,8 @@ PUBLIC_API mysqlx_session_options_t * mysqlx_session_options_new();
   @param opt handle to sessin configuartion data object
              that has to be freed
 
+  @note This function is DEPRECATED. Use `mysqlx_free()` instead.
+
   @ingroup xapi_sess
 */
 
@@ -2214,7 +2215,7 @@ PUBLIC_API int mysqlx_set_update_values(mysqlx_stmt_t *stmt, ...);
            `mysqlx_free()`) or until another call to `mysqlx_execute()`
            on the same statement handle is made. It is also possible to close
            a result handle and free all resources used by it earlier with
-           `mysqlx_result_free()` call.
+           `mysqlx_free()` call.
            On error NULL is returned. The statement is set to an error state and
            errors can be examined using the statement handle.
 
@@ -2491,17 +2492,28 @@ PUBLIC_API int
 mysqlx_set_row_locking(mysqlx_stmt_t *stmt, int locking, int contention);
 
 /**
-  Free the statement handle explicitly.
+  Free the allocated handle explicitly.
 
-  @note Statement handles are also freed automatically when
-  statement's session is closed.
+  After calling this function on a handle it becomes invalid and
+  should not be used any more.
 
-  @param stmt statement handle
+  @note Statement, result, schema, collection, table and some error
+        handles are also freed automatically when the session is closed.
+
+  @note Only errors that originate from an already established session are
+        freed automatically when that session is closed.
+        Errors reported from one of the following functions when they
+        fail to create a new session or a new client must be freed explicitly:
+        `mysqlx_get_session()`, `mysqlx_get_session_from_url()`,
+        `mysqlx_get_session_from_options()`, `mysqlx_get_session_from_client()`,
+        `mysqlx_get_client_from_url()` and `mysqlx_get_client_from_options()`.
+
+  @param obj object handle
 
   @ingroup xapi_stmt
 */
 
-PUBLIC_API void mysqlx_free(mysqlx_stmt_t *stmt);
+PUBLIC_API void mysqlx_free(void *obj);
 
 
 /*
@@ -2799,6 +2811,8 @@ mysqlx_get_double(mysqlx_row_t* row, uint32_t col, double *val);
 /**
   Free the result explicitly.
 
+  @note This function is DEPRECATED. Use `mysqlx_free()` instead.
+
   @note Results are also freed automatically when the corresponding
   statement handle is freed.
 

testapp/xapi_test.c

@@ -68,11 +68,7 @@ int main(int argc, const char* argv[])
 
   const char   *url = (argc > 1 ? argv[1] : "mysqlx://[email protected]");
 
-
-
-  char conn_error[MYSQLX_MAX_ERROR_LEN];
-  int conn_err_code;
-
+  mysqlx_error_t *error;
   int64_t v_sint = -17;
   uint64_t v_uint = 101;
   float v_float = 3.31f;
@@ -88,10 +84,12 @@ int main(int argc, const char* argv[])
     Connect and create session.
   */
 
-  sess = mysqlx_get_session_from_url(url, conn_error, &conn_err_code);
+  sess = mysqlx_get_session_from_url(url, &error);
   if (!sess)
   {
-    printf("\nError! %s. Error Code: %d", conn_error, conn_err_code);
+    printf("\nError! %s. Error Code: %d", mysqlx_error_message(error),
+           mysqlx_error_num(error));
+    mysqlx_free(error);
     return -1;
   }
 
@@ -117,7 +115,7 @@ int main(int argc, const char* argv[])
 
     major_version = atoi(buffer);
 
-    mysqlx_result_free(res);
+    mysqlx_free(res);
 
     if (major_version < 8)
     {

xapi/error_internal.h

@@ -65,9 +65,8 @@ class Mysqlx_exception
 
 typedef struct mysqlx_error_struct mysqlx_error_t;
 
-class Mysqlx_diag_base
+struct Mysqlx_diag_base
 {
-public:
   virtual mysqlx_error_t * get_error() = 0;
 };
 
@@ -80,17 +79,23 @@ typedef struct mysqlx_error_struct : public Mysqlx_diag_base
   mysqlx_error_struct() : m_error_num(0), m_is_warning(false)
   {}
 
-  mysqlx_error_struct(const char *m, unsigned int n, bool is_warning = false) : m_is_warning(is_warning)
+  mysqlx_error_struct(const char *m, unsigned int n,
+                      bool is_warning = false) :
+                      m_is_warning(is_warning)
   {
     set(m, n);
   }
 
-  mysqlx_error_struct(const cdk::Error* cdk_error, bool is_warning = false) : m_is_warning(is_warning)
+  mysqlx_error_struct(const cdk::Error* cdk_error,
+                      bool is_warning = false) :
+                      m_is_warning(is_warning)
   {
     set(cdk_error);
   }
 
-  mysqlx_error_struct(const cdk::Error &cdk_error, bool is_warning = false) : m_is_warning(is_warning)
+  mysqlx_error_struct(const cdk::Error &cdk_error,
+                      bool is_warning = false) :
+                      m_is_warning(is_warning)
   {
     set(&cdk_error);
   }
@@ -150,6 +155,12 @@ typedef struct mysqlx_error_struct : public Mysqlx_diag_base
   {}
 } mysqlx_error_t;
 
+
+struct mysqlx_dyn_error_struct : public mysqlx_error_struct
+{
+  using mysqlx_error_struct::mysqlx_error_struct;
+};
+
 class Mysqlx_diag : public Mysqlx_diag_base
 {
   protected: