CS_USER_ALLOC identifies a user-supplied memory allocation routine that Client-Library uses for memory management while operating at the system interrupt level.
Together, CS_USER_ALLOC and CS_USER_FREE allow an asynchronous application to perform its own memory management.
A user-supplied memory allocation routine must be defined as:
void *user_alloc(size)
size_t size;
Ordinarily, Client-Library routines satisfy their memory requirements by calling malloc. However, not all implementations of malloc are reentrant, so it is not safe to use malloc in Client-Library routines that are called at the system interrupt level. For this reason, on systems where Client-Library uses signal-driven network I/O, such as UNIX systems, fully asynchronous applications are required to provide an alternate way for Client-Library to satisfy its memory needs.
This is not a requirement on platforms that use thread-driven network I/O or for applications that do not use fully asynchronous connections. For a description of the network I/O method used on your platform, see the Open Client and Open Server Programmers Supplement for Microsoft Windows and the Open Client and Open Server Programmers Supplement for UNIX.
Client-Library provides two mechanisms by which an asynchronous application can satisfy Client-Library’s memory requirements:
The application uses the CS_MEM_POOL property to provide Client-Library with a memory pool.
The application uses the CS_USER_ALLOC and CS_USER_FREE properties to install memory allocation and free routines that Client-Library safely calls at the interrupt level.
If a fully asynchronous application fails to provide Client-Library with a safe way to satisfy memory requirements, Client-Library’s behavior is undefined.
Client-Library attempts to satisfy memory requirements from the following sources, in the following order:
Memory pool
User-supplied allocation and free routines
System routines
If a connection cannot get the memory it needs, Client-Library marks the connection dead.
An application may replace a user-defined memory routine by calling ct_config with action as CS_SET and buffer as the address of the new routine.
An application clears a memory routine in two ways:
By calling ct_config with action as CS_SET and buffer as NULL, or
By calling ct_config with action as CS_CLEAR.
