Indy 9 | Content | Index | Reference

TIdThread
Hierarchy, Properties, Methods, Events, See Also, Unit: IdThread
Ancestor for all Indy threads.

    TIdThread = class(TIdBaseThread)

Unit
IdThread
Description
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.

TIdThread.Data
TIdThread, See Also
Storage slot for data used by a thread.

    property Data: TObject;

Description
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.

TIdThread.StopMode
TIdThread, See Also
Determines the action taken when the Stop method is called.

    property StopMode: TIdThreadStopMode;

Description
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.

TIdThread.Stopped
TIdThread, See Also
Indicates whether a thread is stopped.

    property Stopped: Boolean;

Description
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.

TIdThread.TerminatingException
TIdThread, See Also
Contains the text of an Exception.Message raised within the Execute method.

    property TerminatingException: string;

Description
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.

TIdThread.TerminatingExceptionClass
TIdThread, See Also
Represents the class type for an exception raised during Execute.

    property TerminatingExceptionClass: TClass;

Description
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.

TIdThread.Create
TIdThread, See Also
Create is the constructor for the TIdThread instance.

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

Parameters
ACreateSuspended: Boolean = True
Create thread in a suspended state.
Description
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.

TIdThread.Destroy
TIdThread, See Also
Frees a class instance.

    destructor Destroy; override;

Description
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.

TIdThread.Start
TIdThread, See Also
Starts or resumes iteration of the loop in the Execute method.

    procedure Start; virtual;

Description
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.

TIdThread.Stop
TIdThread, See Also
Prevents further execution of the thread.

    procedure Stop; virtual;

Description
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.

TIdThread.Terminate
TIdThread
Forces the thread of execution to be halted.

    procedure Terminate; virtual;

Description
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.

TIdThread.TerminateAndWaitFor
TIdThread, See Also
Signals a thread to terminate and waits for it to finish by exiting the Execute method.

    procedure TerminateAndWaitFor; virtual;

Description
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.

TIdThread.OnException
TIdThread, See Also
Handles exceptions raised in the thread of execution.

    property OnException: TIdExceptionThreadEvent;

Parameters
E
Exception to be handled.
Sender
Object calling the event handler.
Description
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.

TIdThread.OnStopped
TIdThread, See Also
Represents an event handler for stopping a thread of execution.

    property OnStopped: TIdNotifyThreadEvent;

Description
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.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.