Access shared memory

A C UDR executes in a virtual processor, which is associated with an operating-system process. While a C UDR executes on a VP (VP #1), it can access memory that is associated with that virtual processor. This memory space includes the stack, heap, and data segments of the VP.

The following figure shows a schematic representation of what a virtual processor that has loaded a shared-object file looks like internally.

Figure 1. VP memory space for a C UDR

If the UDR needs to perform some non-computational task (such as I/O), the database server migrates its thread to the appropriate VP class. When this non-computational task is complete, the database server migrates the thread back to a computational VP (such as the CPU VP). After the UDR migrates from VP #1 to another VP (VP #2), it no longer has access to any information in the memory space of VP #1. It can now only access the memory space of the new VP. The only memory that the UDR can access from both VP #1 and VP #2 is the database server shared memory. This restriction leads to the following guidelines for the dynamic memory allocation in a C UDR:

The C UDR must be threadsafe.
The UDR must not assume that it can always access information that is stored in the VP memory space. This guideline is part of the requirements for a well-behaved UDR. For more information, see Create a well-behaved routine.
The C UDR must use the DataBlade API memory-management functions to allocate memory dynamically.
The DataBlade API memory-management functions in Table 1 allocate memory from the shared memory of the database server, not from the memory space of a virtual processor, as the following figure shows.

Figure 2. Location of dynamically allocated memory for a C UDR

The DataBlade API memory-management functions allocate memory from shared memory, which remains accessible if a thread migrates to another virtual processor. All VPs can access information in memory that these memory-management functions allocate because all VPs can access the shared memory of the database server.

The system memory-management functions (such as malloc() and calloc()) allocate memory in the heap space of the VP. If a UDR migrates to another VP, it no longer has access to the heap space of the previous VP. Therefore, the address to dynamic memory in some variable is not valid once the UDR executes in the new VP.

Important: A C UDR must dynamically allocate memory from the shared memory of the database server, not from the memory of the VP that runs the UDR. Therefore, a C UDR must use the DataBlade API memory-management functions for all dynamic memory allocation.

To ensure that a C UDR does not retain unnecessary amounts of shared memory, it must use the following guidelines for the dynamic memory allocation:

The C UDR must ensure that it can access both the memory and its address when it needs to.
Both the memory and the memory address must have a memory duration sufficient for all UDRs that need to access the information. For more information, see Memory-duration considerations.
The C UDR must use the DataBlade API memory-management functions to dynamically allocate memory that has an associated memory duration.
The DataBlade API memory-management functions allocate memory from the memory-duration memory pools of the database server shared memory. Therefore, the database server can automatically reclaim this memory, reducing the chance of memory leaks. For more information, see Manage shared memory.