Jump to content

DosAllocThreadLocalMemory: Difference between revisions

From EDM2
Created page with "==Description== Allocates a block of memory that is unique, or local, to a thread. ==Syntax== <PRE> #define INCL_DOSPROCESS #include <os2.h> ULONG cb; /* Number of 4..."
 
Ak120 (talk | contribs)
mNo edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
==Description==
Allocates a block of memory that is unique, or local, to a thread.
Allocates a block of memory that is unique, or local, to a thread.


==Syntax==
==Syntax==
<PRE>
  DosAllocThreadLocalMemory(cb, p)
#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);


</PRE>
==Parameters==
==Parameters==
; cb (ULONG) - input : Number of 4-byte DWORDs to allocate.
;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.
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.
 
; p (PULONG *) - output : Address of the memory block returned by the function.


==Return Code==
==Return Code==
rc (APIRET) - returns
;rc (APIRET) - returns:This function returns one of the following values:
 
* 0 NO_ERROR
This function returns one of the following values:
* 8 ERROR_NOT_ENOUGH_MEMORY
 
*87 ERROR_INVALID_PARAMETER
* 0   NO_ERROR  
* 8   ERROR_NOT_ENOUGH_MEMORY  
* 87   ERROR_INVALID_PARAMETER


==Remarks==
==Remarks==
Line 71: Line 56:
   return NO_ERROR;
   return NO_ERROR;
}
}
</PRE>


</PRE>
==Related Functions==
==Related Functions==
* [[OS2 API:CPI:DosFreeThreadLocalMemory|DosFreeThreadLocalMemory]]
*[[DosFreeThreadLocalMemory]]
 


[[Category:The OS/2 API Project]]
[[Category:Dos]]

Latest revision as of 17:40, 29 November 2019

Allocates a block of memory that is unique, or local, to a thread.

Syntax

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