DosAllocThreadLocalMemory
Description
Allocates a block of memory that is unique, or local, to a thread.
Syntax
#define INCL_DOSPROCESS #include <os2.h> ULONG cb; /* Number of 4-byte DWORDs to allocate. */ PULONG *p; /* Address of the memory block returned by the function. */ APIRET rc; /* Return Code. */ rc = DosAllocThreadLocalMemory(cb, p);
Parameters
- cb (ULONG) - input
- Number of 4-byte DWORDs to allocate.
- Up to 8 DWORDs (32 bytes) can be requested each time this function is called. A maximum of 32 DWORDs (128 bytes) can be allocated in total.
- p (PULONG *) - output
- Address of the memory block returned by the function.
Return Code
rc (APIRET) - returns
This function returns one of the following values:
- 0 NO_ERROR
- 8 ERROR_NOT_ENOUGH_MEMORY
- 87 ERROR_INVALID_PARAMETER
Remarks
When a process is started, a small block of memory is set aside to be used as a thread-local memory area. This memory is at the same virtual address for each thread, but is backed by different physical memory. This permits each thread to have a small block of memory that is unique, or local, to that thread.
The thread-local memory area consists of 32 DWORDs (128 bytes), each DWORD being 4 bytes in size. Up to 8 DWORDs (32 bytes) can be requested each time this function is called. If you want to allocate more than 8 DWORDs, you must call this function more than once.
Allocation is by DWORD only. If you want to store a BYTE in the thread-local memory area, you would still allocate a DWORD, then store the BYTE in it.
Example Code
This example shows how to allocate and free 3 WORDs of local thread memory.
#define INCL_DOSPROCESS
#define INCL_DOSERRORS
#include <os2.h>
#include <stdio.h> /* Needed for printf */
PULONG pulThreadDWords = NULL; /* Pointer to thread DWORDs returned */
APIRET rc = NO_ERROR; /* Return code */
int main(VOID) {
/* Allocate 3 DWORDs of local thread memory */
rc = DosAllocThreadLocalMemory(3, /* Number of DWORDs */
&pulThreadDWords); /* Address returned */
if (rc != NO_ERROR) {
printf("DosAllocThreadLocalMemory error: return code = %u\n", rc);
return 1;
}
/* ... Use the thread-local memory ... */
rc = DosFreeThreadLocalMemory(pulThreadDWords); /* Free the DWORDs */
if (rc != NO_ERROR) {
printf("DosFreeThreadLocalMemory error: return code = %u\n", rc);
return 1;
}
return NO_ERROR;
}