Root > Reference > All Functions > BeginThreadEx

Function BeginThreadEx

 		Previous pageReturn to chapter overviewNext page   

Spawns a separate thread of execution.

 

Unit

EBase

 

Syntax

 

Code (Delphi)

function BeginThreadEx(

SecurityAttributes: Pointer;

StackSize: LongWord;

ThreadFunc: TThreadFunc;

Parameter: Pointer;

CreationFlags: LongWord;

var ThreadId: TThreadID;

const AThreadName: String = '';

const AEnableEL: Boolean = Boolean(2

)): Integer;

 

Parameters

ThreadAttributes [in, opt]

A pointer to a SECURITY_ATTRIBUTES record that determines whether the returned handle can be inherited by child processes. If ThreadAttributes is nil, the handle cannot be inherited.

 

The lpSecurityDescriptor member of the ThreadAttributes record specifies a security descriptor for the new thread. If ThreadAttributes is nil, the thread gets a default security descriptor. The ACLs in the default security descriptor for a thread come from the primary token of the creator.

 

StackSize [in, opt]

The initial size of the stack, in bytes. The system rounds this value to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. For more information, see Thread Stack Size.

 

ThreadFunc [in]

A pointer to the application-defined function to be executed by the thread. This pointer represents the starting address of the thread.

 

Parameter [in, opt]

A pointer to a variable to be passed to the thread.

 

CreationFlags [in, opt]

Set of bits OR'ed together that are drawn from the following:   CREATE_SUSPENDED: The thread is created in a suspended state, and does not run until the ResumeThread function is called. STACK_SIZE_PARAM_IS_A_RESERVATION: The StackSize parameter specifies the initial reserve size of the stack. If this flag is not specified, StackSize specifies the commit size.

 

ThreadId [out]

Receives the thread identifier (TID).

 

AThreadName [in, opt]

Defines thread's name. Thread name is arbitrary text string which can contain any combination of characters. Thread name will be visible in IDE's debugger. It also will be used by EurekaLog in bug reports. Default is empty name (no name; TID will be used to identify this thread).

 

AEnableEL [in, opt]

Defines EurekaLog status in created thread. This argument is ignored if you compile your application without EurekaLog. Default is the same state as current thread.

 

Return value

If the function succeeds, the return value is a handle to the new thread. The handle must be closed via CloseHandle.

 

 

If the function fails, the return value is 0. To get extended error information, call GetLastError.

 

Note

BeginThreadEx may succeed even if ThreadFunc points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread's process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

 

Remarks

BeginThreadEx is EurekaLog's replacement for BeginThread function. BeginThreadEx offers two additional arguments, which allows you to control thread's name and EurekaLog's state in this thread.

 

EurekaLog will automatically handle any unhandled exception inside ThreadFunc (assuming that you did not set AEnableEL to False).

 

Use this routine or a TThreadEx object to spawn separate threads of execution. BeginThreadEx spawns a new thread of execution and sets the global IsMultiThread variable, thereby making the heap thread-safe.

 

The number of threads a process can create is limited by the available virtual memory. By default, every thread has one megabyte of stack space. Therefore, you can create at most 2,048 threads. If you reduce the default stack size, you can create more threads. However, your application will have better performance if you create one thread per processor and build queues of requests for which the application maintains the context information. A thread would process all requests in a queue before processing requests in the next queue.

 

The new thread handle is created with the THREAD_ALL_ACCESS access right. If a security descriptor is not provided when the thread is created, a default security descriptor is constructed for the new thread using the primary token of the process that is creating the thread. When a caller attempts to access the thread with the OpenThread function, the effective token of the caller is evaluated against this security descriptor to grant or deny access.

 

The newly created thread has full access rights to itself when calling the GetCurrentThread function.

 

If the thread is created in a runnable state (that is, if the CREATE_SUSPENDED flag is not used), the thread can start running before BeginThreadEx returns and, in particular, before the caller receives the handle and identifier of the created thread.

 

The thread execution begins at the function specified by the ThreadFunc parameter. If this function returns, the DWORD return value is used to terminate the thread in an implicit call to the ExitThread function. Use the GetExitCodeThread function to get the thread's return value.

 

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

 

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting on the object.

 

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

 

Examples

 

Code (Delphi)

function ThreadFunc(Parameter: Pointer): Integer;

begin

// No additional code needed inside thread func

 

// - ... your code for the thread ...

 

Result := 0; // to indicate "success"

end;

 

procedure TForm1.Button1Click(Sender: TObject);

var

TID: Cardinal;

begin

// This code ignores any failures in thread, but

// you may want to use GetExitCodeThread function.

CloseHandle(BeginThreadEx(nil, 0, ThreadFunc, nil, 0, TID,

// New argument: thread name

'This is my thread with Parameter = ' +

IntToHex(NativeUInt(nil), SizeOf(Pointer) * 2)));

end;

 

Threads launched with BeginThreadEx will be EurekaLog-enabled by default. You can supply optional Boolean argument for BeginThreadEx function to disable EurekaLog in thread, for example:

 

Code (Delphi)

BeginThreadEx(nil, 0, ThreadFunc, nil, 0, TID, 'Thread Name', False { disable EurekaLog in thread } );

 

See also

•SetEurekaLogStateInThread Function


Send feedback... Build date: 2024-09-30
Last edited: 2024-09-30
PRIVACY STATEMENT
The documentation team uses the feedback submitted to improve the EurekaLog documentation. We do not use your e-mail address for any other purpose. We will remove your e-mail address from our system after the issue you are reporting has been resolved. While we are working to resolve this issue, we may send you an e-mail message to request more information about your feedback. After the issues have been addressed, we may send you an email message to let you know that your feedback has been addressed.

Permanent link to this article: https://www.eurekalog.com/help/eurekalog/topic_function_ebase_beginthreadex.php