Ancestor for visual components that implement threaded execution at runtime.

TIdCustomThreadComponent = class(TIdBaseComponent)

TIdCustomThreadComponent is a TIdBaseComponent descendant that is the ancestor class for Indy components that use a TIdThread instance internally during execution. TIdCustomThreadComponent exposes properties, methods, and event handlers that are used to access the underlying protected TIdThread instance, including:

• Active

• Priority

• StopMode

• OnAfterExecute

• OnAfterRun

• OnBeforeExecute

• OnBeforeRun

• OnCleanup

• OnException

• OnRun

• OnStopped

• OnTerminate

• Start

• Stop

• Synchronize

• SynchronizeEx

• Terminate

• TerminateAndWaitFor

• WaitFor

• ReturnValue

• Stopped

• Suspended

• Terminated

TIdCustomThreadComponent allows creation of visual components that can manipulate properties and events handlers in the object inspector at design-time. When the thread becomes Active at runtime, the event handlers for the thread are synchronized to the VCL thread for the component instance.

Note: Some methods in TIdCustomThreadComponent are declared as virtual. Applications should not create instances of TIdCustomThreadComponent. Create instance of a descendant class that implement the virtual methods in the component.

Provides object data for the internal thread of execution.

property Data: TObject;

Data is a TObject property used to provide optional values to the internal thread used in executing the threaded component object. Read and Write access to the Data property is delegated to Data property in the underlying TIdThread instance.

Note: Data is not maintained in either Create or Destroy. Applications must allocate and free the TObject descendant used in the Data property.

Provides access to the thread handle for the component.

property Handle: THandle;

Handle is a read-only THandle property that provides access to the handle allocated to the internal thread used in the thread component object. Read access to Handle calls the GetThreadHandle function for the internal thread instance. Handle can be used when called platform-specific APIs that require a thread handle for thread manipulation.

Represents the return value for the completed thread of execution.

property ReturnValue: Integer;

ReturnValue is a public Integer property that represents the value returned when the internal thread of execution is completed or the threaded component object. ReturnValue indicates success, failure, or the simple numeric result for the thread. Read and write access for ReturnValue is delegated to the underlying thread instance.

Indicates the thread for the component has been halted.

property Stopped: Boolean;

Stopped is a read-only Boolean property that indicates if the internal thread for the component has been asked to halt execution. Stopped read its value from the underlying thread instance used in the implementation of the thread component object. Stopped is also used in determining the value for the Active property when the IDE is not running. Active will be True when Stopped contains False.

Indicates if the thread has been interrupted, but not stopped or terminated.

property Suspended: Boolean;

Suspended is a read-only Boolean property that indicates if the Suspend property for the internal thread has been set to True. The Suspended thread can continue execution when Resume is called.

Check Stopped to determine if Stop has been called for the internal thread. Check Terminated to determine if Terminate has been called for the internal thread.

Indicates a request to Terminate for the internal thread for the component.

property Terminated: Boolean;

Terminated is a read-only Boolean property that indicates when Terminated has been called for the internal thread for the threaded component object. Terminated does not indicate that Terminate method has been successfully completed.

Use Stopped to determine is the internal thread is still running. Call WaitFor to pause until the ReturnValue for a terminating thread is set and thread clean up is performed.

Use TerminateAndWaitFor to force thread termination and pause until its completion.

Message from an exception raised during execution of the internal thread.

property TerminatingException: string;

TerminatingException is a read-only String property that represents the message from an exception raised during execution of the internal thread for the component. Use TerminatingExceptionClass to access the class type for the exeception.

Use OnException to perform exception handling for component using a method synchronized to the main application thread.

Class Type for an exception raised during execution of the internal thread.

property TerminatingExceptionClass: TClass;

TerminatingExceptionClass is a read-only TClass property that represents the class type for an exception raised during execution of the internal thread for the component. Use TerminatingException to access the message from the exception.

Use TIdThreadComponent.OnException to perform exception handling using a method synchronized to the main application thread of execution.

Constructor for the threaded component object instance.

constructor Create(AOwner: TComponent); override;

Owner of the object instance.

Create is the constructor for the threaded component object instance. Create calls the inherited Create method using AOwner of the owner of the object instance. Create allocates the internal thread instance used in implementing the threaded component when the ComponentState contains a value other than csDesigning. Note: In other words, the thread instance is not initialized when an instance is created in the IDE.

Create sets the default value for the StopMode property to IdThreadComponentDefaultStopMode, and sets Priority to IdThreadComponentDefaultPriority prior to exiting from the the method.

Frees the object instance.

destructor Destroy; override;

Destroy is the destructor for the object instance. Destroy frees and release the internal thread instance used in implementing the threaded component. When the thread has been assigned (not in the IDE), Destroy terminates the thread instance and resumes a suspended thread to allow termination to complete. Destroy calls the inherited Destroy method prior to exiting.

Starts or resumes the thread of execution for the component.

procedure Start; virtual;

Start is a virtual procedure in TIdCustomThreadComponent that instructs the internal thread instance for the threaded component object to start or resume execution. Start is called when the value of the Active property is changed from False to True. Note: The internal thread instance is not executed when calling Start and the thread instance is still unassigned (running in the IDE).

Use Stop to halt execution of the internal thread for the component.

Halts execution of the thread for the component.

procedure Stop; virtual;

Stop is a virtual procedure in TIdCustomThreadComponent that halts execution of the internal thread for the threaded component object. Stop is called when the value of the Active property is changed from True to False. Note: The internal thread instance is not halted using Stop when the thread instance is unassigned (in the IDE).

Executes a thread or procedural method in the main application thread.

procedure Synchronize(AMethod: TThreadMethod); overload;
procedure Synchronize(AMethod: TMethod); overload;

Thread or procedural method to be executed in the main thread.

Synchronize is an overloaded method in TIdCustomThreadComponent that causes the thread or procedural method in AMethod to be executed using the VCL thread for the thread component object. Synchronize is used to avoid conflicts in multi-threaded applications.

Use Synchronize to execute a thread or object method that may not be thread-safe when accessing memory or other resources in the application. Use SynchronizeEx to perform thread or procedural methods that required access to the Data property or TIdSynchronizeThreadComponentEvent procedures.

Note: The Execution of the thread is suspended while Method is executing in the main VCL thread.

Executes a thread or procedural method in the main application thread.

procedure Synchronize(AMethod: TThreadMethod); overload;
procedure Synchronize(AMethod: TMethod); overload;

Thread or procedural method to be executed in the main thread.

Synchronize is an overloaded method in TIdCustomThreadComponent that causes the thread or procedural method in AMethod to be executed using the VCL thread for the thread component object. Synchronize is used to avoid conflicts in multi-threaded applications.

Use Synchronize to execute a thread or object method that may not be thread-safe when accessing memory or other resources in the application. Use SynchronizeEx to perform thread or procedural methods that required access to the Data property or TIdSynchronizeThreadComponentEvent procedures.

Note: The Execution of the thread is suspended while Method is executing in the main VCL thread.

Requests that the thread for the component be terminated.

procedure Terminate; virtual;

Terminate is a virtual procedure in TIdCustomThreadComponent that signals the internal thread for the threaded component to halt execution as soon as possible. Terminate results in the Terminated property for the internal thread instance being set to True, but allows the thread to continue execution for normal shut down and clean up.

Waits for termination fo the internal thread for the component.

procedure TerminateAndWaitFor; virtual;

TerminateAndWaitFor is a virtual procedure in TIdCustomThreadComponent that combines the actions of both the Terminate and WaitFor methods of the internal thread for the threaded component object. TerminateAndWaitFor will wait for the Stopped to be set, and then calls WaitFor to get the ReturnValue after completion of the Terminate method call.

Note: Both Terminate and TerminateAndWaitFor depend on the Execute method periodically checking the Terminated property, and exiting when is has been set to True.

Waits until thread execution has been completed.

function WaitFor: LongWord;

WaitFor is LongWord function that delays until the internal thread for the component has completed its Execute method. WaitFor will pause as a result of a call to Terminate or when it has been Stopped and StopMode is smTerminate. The return value for WaitFor is set to the ReturnValue from the internal thread.

Use TerminateAndWaitFor to combine the operations of the Terminate and the WaitFor methods.