DosAllocThreadLocalMemory: Difference between revisions
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..." |
mNo edit summary |
||
(2 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
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== | ||
DosAllocThreadLocalMemory(cb, p) | |||
==Parameters== | ==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. | |||
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 | |||
==Return Code== | ==Return Code== | ||
;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 | |||
* 8 | |||
* 87 | |||
==Remarks== | ==Remarks== | ||
Line 71: | Line 56: | ||
return NO_ERROR; | return NO_ERROR; | ||
} | } | ||
</PRE> | |||
==Related Functions== | ==Related Functions== | ||
* [[ | *[[DosFreeThreadLocalMemory]] | ||
[[Category: | [[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; }