Managing User Memory

Home | Previous Page | Next Page Creating User-Defined Routines > Managing Memory > Managing Shared Memory >

Managing User Memory

A C UDR allocates user memory from the database server shared memory. It is accessed by address. The DataBlade API provides memory-management functions to allocate user memory dynamically. These functions return a pointer to the address of the allocated memory and subsequent operations are performed on that pointer. Table 99 shows the memory-management functions that the DataBlade API provides for memory operations on user memory.

Table 99. DataBlade API User-Memory-Management Functions
User-Memory Task	DataBlade API Function
Allocating user memory	mi_alloc( ), mi_dalloc( ), mi_realloc( ), mi_zalloc( )
Changing the size of an existing memory block	mi_realloc( )
Changing current memory duration	mi_switch_mem_duration( )
Deallocating user memory	mi_free( )

Tip:

The DataBlade API memory-management functions execute in client LIBMI applications as well as C UDRs. For DataBlade API modules that you design to run in both client LIBMI applications and UDRs, use these memory-management functions. For information on the behavior of these memory-management functions in a client LIBMI application, see Appendix A. Writing a Client LIBMI Application.

The following table summarizes the memory operations for user memory.

Memory Duration	Memory Operation	Function Name
Current memory duration	Constructor	mi_alloc( ), mi_dalloc( ), mi_zalloc( )
Current memory duration	Destructor	mi_free( )

Allocating User Memory (Server)

To handle dynamic memory allocation of user memory, use one of the following DataBlade API memory-management functions.

Memory-Allocation Task	DataBlade API Function
To allocate user memory with the current memory duration	mi_alloc( )
To allocate user memory with a specified memory duration	mi_dalloc( )
To allocate user memory with the current memory duration that is initialized with zeros	mi_zalloc( )

These user-memory-allocation functions allocate memory from the shared memory of the database server at a particular memory duration.

Tip:

The DataBlade API library also provides memory-management functions to manage named memory. These named-memory-management functions are advanced functions. Use them only when user-memory-management functions cannot perform the task you need done. For more information, see Managing Named Memory.

Managing the Memory Duration

The current memory duration is the memory duration that applies when the mi_alloc( ) or mi_zalloc( ) function allocates memory. These functions do not specify a memory duration for their allocation. Instead, they use the current memory duration for the memory they allocate. By default, the current memory duration is the default memory duration. The default memory duration is PER_ROUTINE; that is, the database server marks the memory for reclamation when the UDR completes. Therefore, the mi_alloc( ) and mi_zalloc( ) functions allocate memory with a duration of PER_ROUTINE by default.

Subsequent sections provide the following information:

The DataBlade API structures allocated in the current memory duration
How to change the current memory duration

Using the Current Memory Duration

Many of the DataBlade API constructor functions assign the current memory duration to the DataBlade API data type structures that they allocate. Table 100 shows the DataBlade API data type structures that are allocated with the current memory duration.

Table 100. DataBlade API Data Type Structures with the Current Memory Duration
DataBlade API Data Type Structure	DataBlade API Constructor Function	DataBlade API Destructor Function
Collection descriptor (MI_COLL_DESC)	mi_collection_open( ), mi_collection_open_with_options( )	mi_collection_close( )
Collection (MI_COLLECTION)	mi_collection_copy( ), mi_collection_create( ), mi_streamread_collection( )	mi_collection_free( )
Error descriptor (MI_ERROR_DESC)	mi_error_desc_copy( )	mi_error_desc_destroy( )
LO handle (MI_LO_HANDLE)	mi_get_lo_handle( ), mi_lo_copy( ), mi_lo_create( ), mi_lo_expand( ), mi_lo_from_file( ), mi_lo_from_string( )	mi_lo_delete_immediate( ), mi_lo_release( )
LO-specification structure (MI_LO_SPEC)	mi_lo_spec_init( )	mi_lo_spec_free( )
LO-status structure (MI_LO_STAT)	mi_lo_stat( )	mi_lo_stat_free( )
MI_LO_LIST	mi_lo_lolist_create( )	None
Row descriptor (MI_ROW_DESC)	mi_row_desc_create( )	mi_row_desc_free( )
Row structure (MI_ROW)	mi_row_create( ), mi_streamread_row( )	mi_row_free( )
Stream descriptor (MI_STREAM)	mi_stream_init( ), mi_stream_open_fio( ), mi_stream_open_mi_lvarchar( ), mi_stream_open_str( )	mi_stream_close( )
User memory	mi_alloc( ), mi_zalloc( )	mi_free( )
Varying-length structure (mi_lvarchar, mi_sendrecv, mi_impexp, mi_impexpbin)	mi_new_var( ), mi_streamread_lvarchar( ), mi_string_to_lvarchar( ), mi_var_copy( )	mi_var_free( )

To change the memory duration of a DataBlade API data type structure, call the mi_switch_mem_duration( ) function with the desired duration before the DataBlade API function call that allocates the object. For more information, see Changing the Memory Duration.

Important:

All the DataBlade API functions in Table 100 allocate structures with the current memory duration. If you switch the current memory duration, you affect not only explicit allocations you make with mi_alloc( ) or mi_zalloc( ) but the memory allocations that all these DataBlade API constructor functions do as well.

Changing the Memory Duration

The PER_ROUTINE memory duration is the default protection on a region of user memory. You can change the memory duration of user memory to another duration in either of the following ways:

Use mi_dalloc( ) instead of mi_alloc( ) to allocate memory.
The mi_dalloc( ) function works in the same way as mi_alloc( ) but provides the option of specifying the memory duration of the memory to allocate. This function does not switch the current memory duration.
Call mi_switch_mem_duration( ) before you call mi_alloc( ).
The mi_switch_mem_duration( ) function switches the current memory duration. All user-memory allocations by subsequent calls to mi_alloc( ) or mi_zalloc( ) have the new current memory duration.

You can use regular or advanced memory durations for user memory. For most memory allocations in a C UDR, use one of the regular memory-duration constants (PER_ROUTINE, PER_COMMAND, PER_STMT_EXEC, or PER_STMT_PREP).

Important:

Use an advanced memory duration for user memory only if a regular memory duration cannot safely perform the task you need done. These advanced memory durations have long duration times and can increase the possibility of memory leakage.

Changing the current memory duration with mi_switch_mem_duration( ) has an effect on the memory durations of all DataBlade API data type structures that Table 100 lists. It does not have an effect on the memory duration of DataBlade API data type structures allocated at the PER_COMMAND (Table 94) and PER_STMT_EXEC (Table 95) durations or at the advanced memory durations (Table 97).

The mi_switch_mem_duration( ) function returns the previous memory duration. You can use this return value to restore memory duration after performing some allocations at a different duration. The following code fragment temporarily changes the current memory duration from PER_ROUTINE (the default) to PER_COMMAND:

/* Switch current memory duration to PER_COMMAND and save
 * old current memory duration in 'old_mem_dur'
 */
old_mem_dur = mi_switch_mem_duration(PER_COMMAND);

/* Perform allocations for a new current memory duration */
buffer = (char *)mi_alloc(BUFF_SIZE);
new_lvarch = mi_new_var(BUFF_SIZE-1);
save_set = mi_save_set_create(conn);

/* Restore old current memory duration */
(void)mi_switch_mem_duration(old_mem_dur);

In the preceding code fragment, the PER_COMMAND memory duration is in effect for the allocation of user memory that the call to mi_alloc( ) makes. Because the mi_new_var( ) function allocates a new varying-length structure in the current memory duration, this call to mi_new_var( ) allocates the varying-length structure with a PER_COMMAND duration. However, the mi_save_set_create( ) function does not allocate its save-set structure at the current memory duration. Therefore, the call to mi_save_set_create( ) still allocates its save-set structure with the PER_STMT_EXEC duration. The second call to mi_switch_mem_duration( ) restores the current memory duration to PER_ROUTINE.

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