Deallocate user memory

The database server automatically reclaims the user memory that mi_alloc(), mi_dalloc(), and mi_zalloc() allocate. The memory duration of the user memory determines when the database server marks the memory for deallocation.

Tip: If a DataBlade® API function allocates memory to hold its return result, the database server automatically frees this memory when its duration expires unless otherwise noted in its description in function descriptions.
User memory remains valid until one of the following events occurs:
  • The mi_free() function frees the memory.
  • The memory duration expires.
  • The mi_close() function closes the current connection (except memory with a PER_SYSTEM duration).
  • A database server exception is raised.

A C UDR is not allowed to cache information from the database across transaction boundaries. Because the state of the database might change entirely when the current transaction commits, any cached information might be invalid. Therefore, UDRs must reinitialize any database state that they require when the next transaction begins. To enforce the policy of no caching across transactions, the database server automatically reclaims memory marked for deallocation at transaction boundaries. In addition, the database server reclaims memory when specified memory durations expire, usually when a UDR allocates and returns a value.

To conserve resources, use the mi_free() function to explicitly deallocate the user memory once your DataBlade API module no longer needs it. The mi_free() function is the destructor function for user memory.

Keep the following restrictions in mind about memory deallocation:
  • Do not free user memory that you allocate for the return value of a UDR.
  • Do not free memory until you are finished accessing the memory.
  • Do not use mi_free() to deallocate memory that you have not explicitly allocated.
  • Do not use mi_free() for data type structures that other DataBlade API constructor functions allocate.
  • Do not attempt to free user memory after its memory duration has expired.
  • Reuse memory whenever possible. Do not repeat calls to allocation functions if you can reuse the memory for another task.