mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-04-09 15:28:14 +02:00
373 lines
12 KiB
XML
373 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
|
|
Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus
|
|
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0
|
|
International public license.
|
|
|
|
https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
|
|
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt
|
|
|
|
Copyright (c) 1997-2025, by the Lazarus Development Team.
|
|
|
|
-->
|
|
<fpdoc-descriptions>
|
|
<package name="lcl">
|
|
<!--
|
|
====================================================================
|
|
AsyncProcess
|
|
====================================================================
|
|
-->
|
|
<module name="AsyncProcess">
|
|
<short>
|
|
Implements a process with asynchronous event notifications.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<file>asyncprocess.pp</file> implements a process with asynchronous event
|
|
notifications for data availability and process termination. The following
|
|
components are added to the Lazarus IDE component palette:
|
|
</p>
|
|
<p>
|
|
<b>System</b> Tab
|
|
</p>
|
|
<ul>
|
|
<li>TAsyncProcess</li>
|
|
</ul>
|
|
<p>
|
|
<file>asynprocess.pp</file> is part of the Lazarus Component Library (LCL).
|
|
</p>
|
|
</descr>
|
|
|
|
<!-- unresolved references -->
|
|
<element name="Classes"/>
|
|
<element name="Process"/>
|
|
<element name="FileUtil"/>
|
|
<element name="UTF8Process"/>
|
|
<element name="InterfaceBase"/>
|
|
<element name="LCLIntf"/>
|
|
|
|
<element name="TAsyncProcess">
|
|
<short>
|
|
Implements a process with asynchronous notifications for data and termination.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>TAsyncProcess</var> is a <var>TProcessUTF8</var> 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 <var>Output</var> handle, and when the
|
|
process is terminated. TAsyncProcess provides <var>OnReadData</var> and
|
|
<var>OnTerminate</var> event handlers signalled for the corresponding
|
|
asynchronous notifications.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.OnReadData"/>
|
|
<link id="TAsyncProcess.OnTerminate"/>
|
|
<link id="#lazutils.utf8process.TProcessUTF8">TProcessUTF8</link>
|
|
<link id="#fcl.process.TProcess.Output">TProcess.Output</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.FPipeHandler"/>
|
|
<element name="TAsyncProcess.FProcessHandler"/>
|
|
<element name="TAsyncProcess.FOnReadData"/>
|
|
<element name="TAsyncProcess.FOnTerminate"/>
|
|
|
|
<element name="TAsyncProcess.GetNumBytesAvailable">
|
|
<short>
|
|
Gets the value for the NumBytesAvailable property.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>GetNumBytesAvailable</var> is a <var>dword</var> function used to get
|
|
the value for the <var>NumBytesAvailable</var> property. The return value
|
|
contains the value from <var>Output.NumBytesAvailable</var>, or 0 (zero) when
|
|
<var>Options</var> does not include the value <var>poUsePipes</var>.
|
|
</p>
|
|
<p>
|
|
Use <var>NumBytesAvailable</var> to access the value for the property.
|
|
</p>
|
|
<p>
|
|
Use <var>Options</var> to specify the process options enabled for the class
|
|
instance.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.NumBytesAvailable"/>
|
|
<link id="TAsyncProcess.GetNumBytesAvailable"/>
|
|
<link id="#fcl.process.TProcess.Options">TProcess.Options</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TAsyncProcess.GetNumBytesAvailable.Result">
|
|
<short>Value for the property.</short>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.HandlePipeInput">
|
|
<short>
|
|
Implements asynchronous notifications during execution of the process.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>HandlePipeInput</var> is a procedure which implements support for
|
|
asynchronous notifications which occur during execution of the process.
|
|
HandlePipeInput is assigned using <var>AddPipeEventHandler</var> when
|
|
<var>Execute</var> is called.
|
|
</p>
|
|
<p>
|
|
HandlePipeInput examines values in <var>AReasons</var> to determine the
|
|
action for the notification. When AReasons includes the value
|
|
<var>prBroken</var>, the pipe has been closed and <var>UnhookPipeHandle</var>
|
|
is called. When <var>prDataAvailable</var> is included in AReasons, the
|
|
<var>OnReadData</var> event handler is signalled (when assigned).
|
|
</p>
|
|
<p>
|
|
Use <var>OnReadData</var> to respond to arrival of data on the handle for the
|
|
process. Use <var>NumBytesAvailable</var> is determine the number of bytes
|
|
available.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.OnReadData"/>
|
|
<link id="TAsyncProcess.NumBytesAvailable"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TAsyncProcess.HandlePipeInput.AData">
|
|
<short>Data available on the input handle.</short>
|
|
</element>
|
|
<element name="TAsyncProcess.HandlePipeInput.AReasons">
|
|
<short>Reason the data was written for the handler.</short>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.HandleProcessTermination">
|
|
<short>
|
|
Performs actions needed when the process is terminated.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>HandleProcessTermination</var> is a procedure which performs actions
|
|
needed when the process is terminated. HandleProcessTermination is assigned
|
|
using <var>AddProcessEventHandler</var> when <var>Execute</var> is called.
|
|
</p>
|
|
<p>
|
|
HandleProcessTermination calls <var>UnhookProcessHandle</var> and
|
|
<var>UnhookPipeHandle</var> to release the handlers in the class instance.
|
|
HandleProcessTermination signals the <var>OnTerminate</var> event handler
|
|
when it has been assigned.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.Execute"/>
|
|
<link id="TAsyncProcess.UnhookProcessHandle"/>
|
|
<link id="TAsyncProcess.UnhookPipeHandle"/>
|
|
<link id="TAsyncProcess.OnTerminate"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TAsyncProcess.HandleProcessTermination.AData">
|
|
<short>Data for the process notification.</short>
|
|
</element>
|
|
<element name="TAsyncProcess.HandleProcessTermination.AReason">
|
|
<short>Reason(s) for the process notification.</short>
|
|
</element>
|
|
<element name="TAsyncProcess.HandleProcessTermination.AInfo">
|
|
<short>Process exit code.</short>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.UnhookPipeHandle">
|
|
<short>
|
|
Removes the pipe handler assigned for the process.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>UnhookPipeHandle</var> is a procedure used to remove the pipe handler
|
|
assigned for the process in the <var>Execute</var> method. UnhookPipeHandle
|
|
calls <var>RemovePipeEventHandler</var> when a pipe handler has been assigned.
|
|
</p>
|
|
<p>
|
|
<var>UnhookPipeHandle</var> is called from the <var>Destroy</var> method, and
|
|
from <var>HandlePipeInput</var> when the <var>prBroken</var> flag is found in
|
|
the parameters passed to the method.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.Execute"/>
|
|
<link id="#lcl.interfacebase.TPipeReason">TPipeReason</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.UnhookProcessHandle">
|
|
<short>
|
|
Removes the process handler assigned for the process.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>UnhookProcessHandle</var> is a procedure used to remove the process
|
|
handler assigned for the process in the <var>Execute</var> method.
|
|
UnhookProcessHandle calls <var>RemoveProcessEventHandler</var> when a process
|
|
handler has been assigned.
|
|
</p>
|
|
<p>
|
|
<var>UnhookProcessHandle</var> is called from the
|
|
<var>HandleProcessTermination</var> and <var>Destroy</var> methods.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.Execute"/>
|
|
<link id="TAsyncProcess.HandleProcessTermination"/>
|
|
<link id="TAsyncProcess.Destroy"/>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.Execute">
|
|
<short>
|
|
Executes the process.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>Execute</var> is an overridden procedure used to execute the process.
|
|
Execute calls the inherited Execute method on entry.
|
|
</p>
|
|
<p>
|
|
Execute uses values in <var>Options</var> to determine if a process or a pipe
|
|
handler is needed for the class instance. When Options includes the value
|
|
<var>poUsePipes</var>, <var>AddPipeEventHandler</var> is called using
|
|
<var>HandlePipeInput</var> as the pipe handler routine. Set the values in
|
|
Options prior to calling the Execute method.
|
|
</p>
|
|
<p>
|
|
Execute calls <var>AddProcessEventHandler</var> using
|
|
<var>HandleProcessTermination</var> as the process handler routine.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.HandlePipeInput"/>
|
|
<link id="TAsyncProcess.HandleProcessTermination"/>
|
|
<link id="#fcl.process.TProcess.Options">TProcess.Options</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.Destroy">
|
|
<short>
|
|
Destructor for the class instance.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>Destroy</var> is the overridden destructor for the class instance.
|
|
Destroy calls <var>UnhookProcessHandle</var> and <var>UnhookPipeHandle</var>
|
|
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.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.UnhookProcessHandle"/>
|
|
<link id="TAsyncProcess.UnhookPipeHandle"/>
|
|
<link id="#fcl.process.TProcess.Destroy">TProcess.Destroy</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.NumBytesAvailable">
|
|
<short>
|
|
Number of output bytes available from the process.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>NumBytesAvailable</var> is a read-only <var>dword</var> property that
|
|
indicates the number of bytes available on the <var>Output</var> handle for
|
|
the process. <var>GetNumBytesAvailable</var> is the read access specifier for
|
|
the property value. NumBytesAvailable contains the value in
|
|
Output.NumBytesAvailable, or 0 (zero) when <var>Options</var> does not
|
|
contain the value <var>poUsePipes</var>.
|
|
</p>
|
|
<p>
|
|
Set the values for the <var>Options</var> property prior to calling
|
|
<var>Execute</var>.
|
|
</p>
|
|
<p>
|
|
Use <var>OnReadData</var> to respond to the process notification signalled
|
|
when data is available.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.Execute"/>
|
|
<link id="TAsyncProcess.OnReadData"/>
|
|
<link id="#fcl.process.TProcess.Options">TProcess.Options</link>
|
|
<link id="#fcl.process.TProcess.Output">TProcess.Output</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.OnReadData">
|
|
<short>
|
|
Event handler signalled when output data is available for the process.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>OnReadData</var> is a <var>TNotifyEvent</var> 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
|
|
<var>Output</var> handle up to the number of bytes in
|
|
<var>NumBytesAvailable</var>. All available data must be handled, or the
|
|
procedure will be called repeatedly until no more data is available.
|
|
</p>
|
|
<p>
|
|
OnReadData is signalled (when assigned) from the <var>HandlePipeInput</var>
|
|
method when the <var>prDataAvailable</var> flag is found in the parameters
|
|
passed to the method.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.NumBytesAvailable"/>
|
|
<link id="#lcl.interfacebase.TPipeReason">TPipeReason</link>
|
|
<link id="#fcl.process.TProcess.Output">TProcess.Output</link>
|
|
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TAsyncProcess.OnTerminate">
|
|
<short>
|
|
Event handler signalled when the process is terminated.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>OnTerminate</var> is a <var>TNotifyEvent</var> 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.
|
|
</p>
|
|
<p>
|
|
OnTerminate is signalled (when assigned) from the
|
|
<var>HandleProcessTermination</var> method, and occurs after the process and
|
|
pipe handlers have been unhooked in the class instance.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TAsyncProcess.HandleProcessTermination"/>
|
|
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="Register">
|
|
<short>Registers components for use in the Lazarus IDE.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Register</var> is the procedure used to register components for use in
|
|
the Lazarus IDE. The following components are added to the Lazarus IDE
|
|
component palette:
|
|
</p>
|
|
<p>
|
|
<b>System</b> Tab
|
|
</p>
|
|
<ul>
|
|
<li>TAsyncProcess</li>
|
|
</ul>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
|
|
</module>
|
|
<!-- AsyncProcess -->
|
|
</package>
|
|
</fpdoc-descriptions>
|