Header File 

process.h 

Category 

Process Control Routines 

Prototype 

_PTHREAD_ADOPTION_DATA _adopt_thread(void (_USERENTRY *__start_address)(void *), void * __arglist, int free_flag ); 

Description 

“Adopts” a thread, created with the Windows API CreateThread function, to the C++Builder RTL by hooking up the necessary internal data (exceptions, stack info, and so forth). _adopt_thread thereby allows the RTL to handle exception issues in that thread. The execution path of this thread is then transferred to another function (the adoptive thread function). From the RTL's perspective, during the execution of this adoptive thread function, the thread appears as if it had been created by a call to _beginthreadex and is allowed all the benefits, such as calling other RTL functions and throwing/catching exceptions. 

To create a thread, a user normally calls _beginthread. This hooks up the internal data automatically. _adopt_thread is primarily used in cases in which this internal data is not present. For example, this happens when a user is called from a thread that came from an outside source, such as ISAPI. 

Using _adopt_thread thereby allows C++Builder compiled DLLs to be used from non-C++Builder EXEs. _adopt_thread works by:

• calling the user function (passing in the arglist param)
• unhooking the exception information
• returning a handle to the thread context

This process allows the same function to be used again (without reallocating all that data). At the end of this cycle, the _unadopt_thread function can be called to finally free up the rest of this data. 

The last parameter, free_flag, determines whether the thread data structures are freed upon function exit:

• If free_flag is zero, then when the adoptive function exits only its exception handler is un-hooked. The rest of the RTL specific data that had been allocated during the thread's adoption, remains valid. If the same thread then calls _adopt_thread again, the existing data is used, the exception handler is rehooked, and the specified adoptive thread function is called.
• If free_flag is set to non-zero, the thread data structures will be freed before _adopt_thread returns. In this case the returned thread handle will be NULL since its associated date has already been freed.

Return Value 

If the __free_flag parameter is false (zero), _adopt_thread returns a handle (thread context) that can later be used to free these data structures by passing it to _unadopt_thread(). 

If the __free_flag parameter to _adopt_thread is non-zero, the thread data is freed before _adopt_thread returns, and the returned handle is NULL. 

If an error has occurred, errno is set to: 

ENOMEM Not enough memory 

Portability