# 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.