Ancestor for all Indy threads.

TIdThread = class(TIdBaseThread)

TIdThread is a descendant of the Delphi TThread, and the ancestor of thread classes used in Indy. Create a descendant of TIdThread to represent a thread of execution in a multi-threaded application.

TIdThread extends the functionality of TThread to include flexible methods for control of thread state and notification of changes to thread state.

TIdThread implements the inherited abstract Execute method to provide a known thread execution mechanism. Execute can detect thread termination, suspend and resume threads, and provide exception handling for an exception raised during thread execution. Execute also provides finer control of thread execution by extending TThread to include the equivalent of thread event handlers.

TIdThread and descendants should override the abstract Run method, and implement the virtual methods BeforeRun and AfterRun.

The Execute method iterates through a loop, making calls to BeforeRun, Run, and AfterRun to provide thread functionality. This loop can be stopped by calling the Stop method. Use the Start method to begin or resume execution of the loop.

TIdThread descendants can be used in conjunction with a TIdThreadMgr descendants to address the overhead issues associated with thread creation and resource allocation in a multi-threaded application.

Note: Do not use properties and methods of other objects directly in the Run method of a thread. Use the Synchronize method to call a procedure that can access objects and resources which are not thread-safe.

Storage slot for data used by a thread.

property Data: TObject;

Data is a TObject property, and can contain a reference to any TObject descendant. Data can be used to store an object reference that will be required by the TIdThread descendant in either Run, BeforeRun, or AfterRun methods.

Note: It is the responsibility of the TIdThread descendant to cast Data to the class instance required by the TIdThread descendant, or an exception will be raised.

Data is not initialized in the Create constructor, but is released in the Destroy destructor.

Determines the action taken when the Stop method is called.

property StopMode: TIdThreadStopMode;

TIdThreadStopMode type defines the possible values for the StopMode property of the TIdThread component, as defined below.

• smTerminate - The thread should be terminated.

• smSuspend - The thread should be suspended.

Indicates whether a thread is stopped.

property Stopped: Boolean;

Stopped is True if the thread has been asked to stop, which means the loop in the Execute method will not iterate until a call to the Start method is made.

Note that a thread may still be executing even if its Stopped property is True.

Contains the text of an Exception.Message raised within the Execute method.

property TerminatingException: string;

TerminatingException is updated in the Execute method from a try...except block prior to triggering the OnException event for the Exception and terminating the thread.

Represents the class type for an exception raised during Execute.

property TerminatingExceptionClass: TClass;

TerminatingExceptionClass is a read-only TClass property that represents the class type for an exception raised during the Execute method for the thread. Use TerminatingException to access the message for the exception raised. Use OnException to implement immediate exception handling prior to exiting from the Execute method and calling Terminate for the thread.

Create is the constructor for the TIdThread instance.

constructor Create(ACreateSuspended: Boolean = True); virtual;

Create thread in a suspended state.

Create relies on the inherited Create constructor to initialize the object instance. In Create, Stopped is set to the value in the ACreateSuspended parameter. If ACreateSuspended is True, you should call the Start method in order to start thread execution. If ACreateSuspended is False, the thread automatically starts its execution.

Create insures that GNotifyThread contains a valid TIdNotifyThread instance prior to extiing from the method.

Frees a class instance.

destructor Destroy; override;

Destroy is the destructor for the object instance, and is responsible for releasing any TObject reference in Data. Destroy relies on the inherited Destroy method to free the object instance.

Starts or resumes iteration of the loop in the Execute method.

procedure Start; virtual;

Start instructs the thread instance to start or resume iterating through the main thread of execution for the thread.

If Stopped is True when Start is called, the values of Stopped and the inherited Suspended property are set to False, and the main thread of execution is allowed to continue.

Prevents further execution of the thread.

procedure Stop; virtual;

When Stop is called, Stopped is set to True, meaning the executing thread method will not allow additional iterations. Depending on the value of the StopMode property, the thread will be terminated or allow suspension from the thread of execution.

When the Stop method is called, it immediately returns, but the thread may have to wait for completion of thread of execution before it can be suspended or terminated. In contrast, if the TerminateAndWaitFor method is called instead, it returns only after the thread has left the main thread of execution.

If you want to immediately suspend the thread, you should set Suspended to true.

Forces the thread of execution to be halted.

procedure Terminate; virtual;

Terminate is a virtual procedure in TIdThread that forces the thread of execution to be halted. Calling Terminate causes the Terminated property to be updated to True.

Terminate will be called in Execute when an exception is raised during execution of the thread. Terminate is also called when Stop is executed and StopMode contains smTerminate.

Signals a thread to terminate and waits for it to finish by exiting the Execute method.

procedure TerminateAndWaitFor; virtual;

TerminateAndWaitFor calls the inherited Terminate method, sets Stopped to True, and calls the inherited WaitFor method. Unlike WaitFor in the ancestor TThread class, the value returned from WaitFor is not used.

Handles exceptions raised in the thread of execution.

property OnException: TIdExceptionThreadEvent;

Exception to be handled.

Object calling the event handler.

OnException is a TIdExceptionEvent event handler that allows the application to specify how execeptions are handled in the multi-threaded program. Write an OnException event handler procedure to provide special processing when the thread encounters an Exception in the Execute method.

Note: Do not free the thread object within this event handler. Allow the OnException event handler to return to the thread context for proper thread termination.

The text portion of the Exception message can also be found in TerminatingException.

Represents an event handler for stopping a thread of execution.

property OnStopped: TIdNotifyThreadEvent;

OnStopped is a TIdNotifyThreadEvent event handler triggered when an executing thread indicates that it has been stopped. OnStopped can be used to restart or terminate the thread, or to perform processing required when the thread of execution has been completed.

Applications must assign a procedure to the event handler to allow a response to the event notification.