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;
}

Related Functions

• DosFreeThreadLocalMemory