Manage named memory

Named memory is memory allocated from the database server shared memory, as user memory. You can, however, assign a name to a block of named memory and then access this memory block by name and memory duration. The database server stores the name and its corresponding address internally. By contrast, user memory is always accessed by its address.

The disadvantage of user memory is that the database server deallocates PER_COMMAND, PER_STMT_EXEC, PER_STMT_PREP, and PER_STATEMENT memory after the command or statement completes. Because a UDR might execute many times for a particular SQL statement (once for each row processed), you might want to retain the memory pointer across all calls to the same UDR.
Tip: The DataBlade® API named-memory-management functions execute only in C UDRs. Do not use these memory-management functions in client LIBMI applications. For DataBlade API modules that you design to run in both client LIBMI applications and UDRs, use the user-memory-management functions. For information aboutmemory management in a client LIBMI application, see Write a client LIBMI application.
To save memory across invocations of a UDR, you can perform one of the following tasks:
  • You can save the memory pointer as part of the user state in the MI_FPARAM structure that is associated with the UDR.

    For more information, see Saving a user state.

  • You can allocate named memory with an appropriate memory duration.

    The advantage of named memory is that it is global within the memory duration it was allocated. Therefore, it can be accessed by many UDRs that execute in the context of many queries, or even by more than one session. Named memory is useful as global memory for caching data across UDRs or for sharing memory between UDRs executing in the context of many SQL statements.

Possible uses for named memory follow:
  • Semi-static lookup information that can be shared among UDRs or sessions
  • Caching function descriptors at the session level for repeated calls to mi_routine_exec()
  • Index methods that need to store global information for an index scan across a fragmented index
The DataBlade API provides the memory-management functions to dynamically allocate named memory in a C UDR. These functions return a name of the named-memory block and subsequent operations are performed on that name and memory duration. The following table shows the memory-management functions that the DataBlade API provides for memory operations on named memory.
Table 1. DataBlade API named-memory-management functions
Named-memory task DataBlade API functions
Allocating named memory mi_named_alloc(), mi_named_zalloc()
Obtaining an allocated named-memory block mi_named_get()
Controlling concurrency mi_lock_memory(), mi_try_lock_memory(), mi_unlock_memory()
Deallocating named memory mi_named_free()
Important: These advanced memory-management functions can adversely affect your UDR if you use them incorrectly. Use them only when the regular DataBlade API user-memory-management functions cannot perform the task you need done.
The minmprot.h header file defines the functions and data type structures of the named-memory-management functions. The minmmem.h header file automatically includes the minmprot.h header file. However, the mi.h header file does not automatically includes minmmem.h. To access the named-memory-management functions, you must include minmmem.h in any DataBlade API routine that calls these functions.
Tip: Each of the named-memory functions in DataBlade API named-memory-management functions have tracepoints in them that generate output when the trace level is greater than zero (0). The output consists of the function name and the arguments passed to it. For more information abouttracepoints, see Tracing.
The following table summarizes the memory operations for named memory.
Memory duration Memory operation Function name
Specified memory duration Constructor mi_named_alloc(), mi_named_zalloc()
Specified memory duration Destructor mi_named_free()