Implements a process with asynchronous event notifications.

asyncprocess.pp implements a process with asynchronous event notifications for data availability and process termination. The following components are added to the Lazarus IDE component palette:

System Tab

- TAsyncProcess

Implements a process with asynchronous notifications for data and termination.

TAsyncProcess is a TProcessUTF8 descendant which implements support for asynchronous notifications when data is available for the process. Internally, TAsyncProcess uses pipe and process handlers to detect when data is written to the Output handle, and when the process is terminated. TAsyncProcess provides OnReadData and OnTerminate event handlers signalled for the corresponding asynchronous notifications.

TProcessUTF8 TProcess.Output
Gets the value for the NumBytesAvailable property.

GetNumBytesAvailable is a dword function used to get the value for the NumBytesAvailable property. The return value contains the value from Output.NumBytesAvailable, or 0 (zero) when Options does not include the value poUsePipes.

Use NumBytesAvailable to access the value for the property.

Use Options to specify the process options enabled for the class instance.

TProcess.Options
Value for the property.
Implements asynchronous notifications during execution of the process.

HandlePipeInput is a procedure which implements support for asynchronous notifications which occur during execution of the process. HandlePipeInput is assigned using AddPipeEventHandler when Execute is called.

HandlePipeInput examines values in AReasons to determine the action for the notification. When AReasons includes the value prBroken, the pipe has been closed and UnhookPipeHandle is called. When prDataAvailable is included in AReasons, the OnReadData event handler is signalled (when assigned).

Use OnReadData to respond to arrival of data on the handle for the process. Use NumBytesAvailable is determine the number of bytes available.

Data available on the input handle.
Reason the data was written for the handler.
Performs actions needed when the process is terminated.

HandleProcessTermination is a procedure which performs actions needed when the process is terminated. HandleProcessTermination is assigned using AddProcessEventHandler when Execute is called.

HandleProcessTermination calls UnhookProcessHandle and UnhookPipeHandle to release the handlers in the class instance. HandleProcessTermination signals the OnTerminate event handler when it has been assigned.

Data for the process notification.
Reason(s) for the process notification.
Process exit code.
Removes the pipe handler assigned for the process.

UnhookPipeHandle is a procedure used to remove the pipe handler assigned for the process in the Execute method. UnhookPipeHandle calls RemovePipeEventHandler when a pipe handler has been assigned.

UnhookPipeHandle is called from the Destroy method, and from HandlePipeInput when the prBroken flag is found in the parameters passed to the method.

TPipeReason
Removes the process handler assigned for the process.

UnhookProcessHandle is a procedure used to remove the process handler assigned for the process in the Execute method. UnhookProcessHandle calls RemoveProcessEventHandler when a process handler has been assigned.

UnhookProcessHandle is called from the HandleProcessTermination and Destroy methods.

Executes the process.

Execute is an overridden procedure used to execute the process. Execute calls the inherited Execute method on entry.

Execute uses values in Options to determine if a process or a pipe handler is needed for the class instance. When Options includes the value poUsePipes, AddPipeEventHandler is called using HandlePipeInput as the pipe handler routine. Set the values in Options prior to calling the Execute method.

Execute calls AddProcessEventHandler using HandleProcessTermination as the process handler routine.

TProcess.Options
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy calls UnhookProcessHandle and UnhookPipeHandle to remove the handler(s) for the class instance. Destroy calls the inherited method to free resources allocated in the class instance and perform free notifications.

TProcess.Destroy
Number of output bytes available from the process.

NumBytesAvailable is a read-only dword property that indicates the number of bytes available on the Output handle for the process. GetNumBytesAvailable is the read access specifier for the property value. NumBytesAvailable contains the value in Output.NumBytesAvailable, or 0 (zero) when Options does not contain the value poUsePipes.

Set the values for the Options property prior to calling Execute.

Use OnReadData to respond to the process notification signalled when data is available.

TProcess.Options TProcess.Output
Event handler signalled when output data is available for the process.

OnReadData is a TNotifyEvent property that implements the event handler signalled when data is available for the process. Applications should assign a procedure to the event handler that responds to the pipe notification. The procedure must handle all data available on the Output handle up to the number of bytes in NumBytesAvailable. All available data must be handled, or the procedure will be called repeatedly until no more data is available.

OnReadData is signalled (when assigned) from the HandlePipeInput method when the prDataAvailable flag is found in the parameters passed to the method.

TPipeReason TProcess.Output TNotifyEvent
Event handler signalled when the process is terminated.

OnTerminate is a TNotifyEvent property that implements the event handler signalled when the process is terminated. Applications can assign a procedure to the event handler to perform actions needed when the process is terminated.

OnTerminate is signalled (when assigned) from the HandleProcessTermination method, and occurs after the process and pipe handlers have been unhooked in the class instance.

TNotifyEvent
Registers components for use in the Lazarus IDE.

Register is the procedure used to register components for use in the Lazarus IDE. The following components are added to the Lazarus IDE component palette:

System Tab

- TAsyncProcess