Indy 9 | Content | Index | Reference

TIdCustomThreadComponent
Hierarchy, Properties, Methods, See Also, Unit: IdThreadComponent
Ancestor for visual components that implement threaded execution at runtime.

    TIdCustomThreadComponent = class(TIdBaseComponent)

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

TIdCustomThreadComponent.Data
TIdCustomThreadComponent, See Also
Provides object data for the internal thread of execution.

    property Data: TObject;

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

TIdCustomThreadComponent.Handle
TIdCustomThreadComponent, See Also
Provides access to the thread handle for the component.

    property Handle: THandle;

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

TIdCustomThreadComponent.ReturnValue
TIdCustomThreadComponent, See Also
Represents the return value for the completed thread of execution.

    property ReturnValue: Integer;

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

TIdCustomThreadComponent.Stopped
TIdCustomThreadComponent, See Also
Indicates the thread for the component has been halted.

    property Stopped: Boolean;

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

TIdCustomThreadComponent.Suspended
TIdCustomThreadComponent, See Also
Indicates if the thread has been interrupted, but not stopped or terminated.

    property Suspended: Boolean;

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

TIdCustomThreadComponent.Terminated
TIdCustomThreadComponent, See Also
Indicates a request to Terminate for the internal thread for the component.

    property Terminated: Boolean;

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

TIdCustomThreadComponent.TerminatingException
TIdCustomThreadComponent, See Also
Message from an exception raised during execution of the internal thread.

    property TerminatingException: string;

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

TIdCustomThreadComponent.TerminatingExceptionClass
TIdCustomThreadComponent, See Also
Class Type for an exception raised during execution of the internal thread.

    property TerminatingExceptionClass: TClass;

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

TIdCustomThreadComponent.Create
TIdCustomThreadComponent, See Also
Constructor for the threaded component object instance.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Owner of the object instance.
Description
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.

TIdCustomThreadComponent.Destroy
TIdCustomThreadComponent, See Also
Frees the object instance.

    destructor Destroy; override;

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

TIdCustomThreadComponent.Start
TIdCustomThreadComponent, See Also
Starts or resumes the thread of execution for the component.

    procedure Start; virtual;

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

TIdCustomThreadComponent.Stop
TIdCustomThreadComponent, See Also
Halts execution of the thread for the component.

    procedure Stop; virtual;

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

TIdCustomThreadComponent.Synchronize
TIdCustomThreadComponent, See Also
Executes a thread or procedural method in the main application thread.

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

Parameters
AMethod: TThreadMethod
Thread or procedural method to be executed in the main thread.
Description
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.

TIdCustomThreadComponent.Synchronize
TIdCustomThreadComponent, See Also
Executes a thread or procedural method in the main application thread.

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

Parameters
AMethod: TThreadMethod
Thread or procedural method to be executed in the main thread.
Description
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.

TIdCustomThreadComponent.Terminate
TIdCustomThreadComponent, See Also
Requests that the thread for the component be terminated.

    procedure Terminate; virtual;

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

TIdCustomThreadComponent.TerminateAndWaitFor
TIdCustomThreadComponent, See Also
Waits for termination fo the internal thread for the component.

    procedure TerminateAndWaitFor; virtual;

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

TIdCustomThreadComponent.WaitFor
TIdCustomThreadComponent, See Also
Waits until thread execution has been completed.

    function WaitFor: LongWord;

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

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