引擎初始化

当打开并连接到数据库，即可通过定义为 database_t 类型的 SQL 数据库“引擎”结构来执行对数据库的 SQL 访问。此结构用于对所有 mcosql_* 函数的调用。

根据应用程序管理动态内存分配的方式，数据库引擎可以通过两种方式创建。最简单的方法如以下代码片段所示：

    /* Create a SQL engine */
    rc = (MCO_RET)mcoapi_create_engine(db, &engine);
                
    if ( MCO_S_OK == rc ) 
    {
        /* Do database processing ... */
        /* Destroy the SQL engine */
         
        rc = (MCO_RET)mcoapi_destroy_engine( engine );
                
         
        /* Disconnect from and close the database, then free database memory */
        rc = mco_db_disconnect(db);
        rc = mco_db_close(db_name);
        free( dev.dev.conv.ptr );
    }

mcoapi_create_engine() 和 mcoapi_destroy_engine() 这对函数负责与 SQL 数据库引擎相关的所有初始化和清理工作。

不过，应用程序仍需负责断开与数据库的连接、关闭数据库以及释放数据库内存。使用此方法时，SmartESQL 运行时会为所有 SQL 处理（例如解析和编译 SQL 语句、生成结果集等）内部调用标准 C 运行时动态内存分配函数 malloc() 和 free() 。

由于这些内存需求可能很大且难以预测，因此一些应用程序更愿意使用自定义内存管理函数来管理动态内存。

为了允许这样做，提供了第二种方法，如以下代码片段所示：

    #define ALLOC_QUANTUM   1024*1024
    #define ALLOC_RETAIN    8*1024*1024
     
    /* define custom memory management functions */
    void * mem_alloc( size_t n_bytes )
    {
        buffer = (void*)malloc( n_bytes );
        printf("\n\n\tmem_alloc(): %u bytes allocated at address 0x%" INT8_FORMAT "x\n",
        (unsigned int)n_bytes, (int64_t)buffer);
        return buffer;
    }
     
    void mem_free( void * buf )
    {
        printf("\n\tmem_free(): memory freed at address 0x%" INT8_FORMAT "x\n", (int64_t)buf);
        free(buf);
    }
     
    /* connect to the database by name */
    rc = mco_db_connect( db_name, &db );
     
    if ( MCO_S_OK == rc ) 
    {
        /* Set SQL memory allocator to custom malloc/free */
        rs = mcosql_initialize_dynamic_memory_manager(
					&mem_alloc, &mem_free,
                
        ALLOC_QUANTUM, ALLOC_RETAIN);
         
        /* Initialize SmartEDB SQL mapper */
        rs = mcoapi_initialize(db);
                
         
        /* Open SQL engine */
        rs = mcosql_open( &engine );
                
         
        /* Do normal database processing ... */
        /* Close SQL engine and disconnect from database */
        rs = mcosql_close( engine );
                
    }
     
    /* close the database, shutdown runtime and free database memory */
    rc = mco_db_close(db_name);
    mco_runtime_stop();
    free( dev.dev.conv.ptr );

请注意此示例代码中的以下关键内容：

基于标准的 malloc() 和 free() 实现，定义了两个自定义内存管理函数 mem_alloc() 和 mem_free()。通过 printf() 输出内存操作信息，以供调试和验证。尽管此处提供的实现较为简单，但可根据实际需求扩展为更复杂的自定义内存管理方案。
调用 mcosql_initialize_dynamic_memory_manager() 函数将上述自定义内存管理函数注册并初始化到 SmartESQL 运行时环境中。该函数接受两个预定义参数 ALLOC_QUANTUM 和 ALLOC_RETAIN，分别用于指定运行时所需的分配块大小和总内存分配限制。
通过调用 mcoapi_initialize(db) 函数将运行时内部映射至 SQL 数据库引擎。
在完成上述准备步骤后，使用 mcosql_open(&engine) 函数创建 SQL 数据库引擎实例。
初始化 SQL 数据库引擎后，可通过调用 mcosql_close() 函数断开数据库连接并释放相关资源。需要注意的是，在这种情况下无需调用 mco_db_disconnect()，但仍需调用 mco_db_close() 关闭数据库连接。返回代码变量 rs 用于区分 SQL 返回代码（定义于头文件 include/sql/sqlc.h）与 SmartEDB 运行时代码（定义于头文件 include/mco.h），以便进行错误处理。