Managing the eXtremeSQL Free Memory Threshold in C++

When a transient database runs out of memory in the middle of an update transaction, it is quite possible that the transaction won’t be able to be rolled back. The rollback requires memory to rebuild internal structures, rebalance trees, etc. The core runtime handles this scenario through allowing applications to set the allocation threshold and monitoring these thresholds through callbacks. (Please refer to the “Monitoring Database Storage Space Consumption” page for further details). The idea behind this technique is to prevent the out-of-memory conditions, rather than attempting to handle them when resources are unavailable.

The McoSqlEngine class includes two methods that help deal with out-of-memory conditions:

 
    void McoSqlEngine::setFreeMemoryThreshold(size_t threshold);
     
    size_t McoSqlEngine::getFreeMemoryThreshold();
     

The first method defines the amount of free database memory (in bytes) that will be available in the database pool for the SQL engine to continue processing. This setting depends on the database access patterns: some SQL statements don't require much memory, some are very memory intensive. If the required memory is not available, the current transaction is rolled back and raises the NotEnoughMemory exception. The second method returns the current threshold level.

The default memory threshold is zero; i.e. no memory is reserved up-front, it must be explicitly set for each McoSqlEngine instance. The McoSqlEngine threshold value is inherited in McoSqlSession and SqlServer objects through the constructor. For example, the following code snippet sets the memory threshold in an engine to 1Mb:

 
    McoSqlEngine engine;
     
    engine.open(...);
    engine.setFreeMemoryThreshold(1024*1024); // set threshold 1 Mbytes
     

Now a SqlServer or a McoSqlSession object with the same 1 Mb memory threshold can be instantiated as follows:

 
    SqlServer *server = new SqlServer(engine, ...); // server has threshold = 1 Mbytes
     
    McoSqlSession session(engine);                  // session has threshold = 1 Mbytes
     

The memory threshold in any of these objects can now be overridden as desired:

 
    session.setFreeMemoryThreshold(4*1024*1024); // override threshold for this session,
                                // set it to 4 Mbytes
                                 
    server.setFreeMemoryThreshold(0); 	     // disable threshold for this server
     

The threshold can also be modified through SQL by calling function set_free_memory_threshold(). For example:

 
    select set_free_memory_threshold(1024*512);
     

The xSQL utility sets the memory threshold when operating as server to 1 Mb by default. This value can be modified through the config file setting free_memory_threshold . For example:

 
    free_memory_threshold : 4M,  # 4 Mbytes
     

When xSQL is used as a client, the memory threshold can be modified at any time by calling the set_free_memory_threshold() function.