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
Table 1 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() |