The IDL_IDLBridge object class allows an IDL session to create and control other IDL sessions, each of which runs as a separate process. Each instantiation of an IDL_IDLBridge object corresponds to one such child process. Child processes are controlled by the parent IDL process - the IDL process that created the IDL_IDLBridge objects. IDL_IDLBridge objects support the following operations:
- Exchanging data between the parent IDL process and the child process by copying IDL variables between them using the SetVar and GetVar methods.
- Executing arbitrary IDL commands in the child process. In synchronous operation, the parent IDL session waits for the child to complete the specified task before continuing. In asynchronous operation, the parent IDL session does not wait, and the two processes run in parallel.
- Querying the current status of the child process while it asynchronously executes an IDL command.
- Registering a callback that is called when an asynchronous command finishes execution.
- Aborting a currently running asynchronous command in a child process.
Using these facilities, one or more IDL_IDLBridge child processes can be used to perform work in parallel with each other and with the parent IDL process that starts them.
In general, IDL_IDLBridge child processes do not inherit state information from the parent IDL process. This means that the child process will not have access to data, compiled routines, system variables, or the current working directory of the parent process. The exception to this rule is that IDL_IDLBridge child processes have the same garbage collection enabled/disabled setting as the parent session. For example, if garbage collection is disabled for the parent process, it will also be disabled for the child process.
An IDL_IDLBridge object child process is designed to perform computationally intensive, background processing tasks while you continue working with the main IDL program. It is not designed to provide asynchronous interaction with interactive user interfaces.
A startup file is not automatically executed when a child process is created.
Note: The Execute, GetVar, and SetVar methods to the IDL_IDLBridge object are disabled in IDL Virtual Machine mode. As a result, while it is possible to create an IDL_IDLBridge object in code that runs in the IDL Virtual Machine, it is not particularly useful.
Superclasses
None
Creation
See IDL_IDLBridge::Init.
Properties
Objects of this class have the following properties. See IDL_IDLBridge Properties for details on individual properties.
Methods
This class has the following methods:
Examples
The following sections provide several examples of creating and using IDL_IDLBridge objects:
About Debugging Child Processes
Debugging a routine running in a child IDL process presents challenges not present when debugging routines running in the main IDL process. Child IDL processes have no direct connection to the parent IDL process. Because of this lack of connection, the following conditions exist:
- The IDL Workbench's debugging tools are not available
- Breakpoints are not honored
- Output from PRINT statements will not appear in the output log
To work around these issues, develop and debug routines in an interactive IDL process before running them in a child process. Once you are ready to test your routines in a child process, consider using one or more of the following approaches:
- Consider writing status and error information generated by the routines in the child process to a text file. This can be easily accomplished by setting the OUTPUTproperty.
- Display debugging output using DIALOG_MESSAGE rather than PRINT
- Use the IDL_IDLBridge::Status method to check for completion status of the entire routine
Note: For information on how to return HELP information for a child process, see the Examples section of IDL_IDLBridge::GetVar.
Note: On Windows, you can see debug output generated by the IDL_BRIDGE_DEBUG environment variable in the Debug Monitor (DBMON.exe), available with the Windows Platform SDK. Use the IDL_BRIDGE_DEBUG environment variable setting to control the level of debug output detail.
Multiple Child Processes Example
This example lets you create and interact with a number of child processes where each process executes an IDL command asynchronously. This means that multiple IDL child processes can be completing tasks while the main IDL process remains active. This demonstration of the IDL_IDLBridge functionality can be used as a guide when using the IDL_IDLBridge object in your own code.
Tip: You can also investigate the effect of executing commands synchronously by commenting out the NOWAIT keyword in the Execute method call.
This example idlbridge_demo.pro, is located in the examples/doc/bridges subdirectory of the IDL distribution. Run the example procedure by entering idlbridge_demo at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT idlbridge_demo.pro.
Run the program and click Execute to launch an asynchronous child process that plots a surface in another window. Create additional IDL_IDLBridge objects by selecting File > New. Since these processes execute commands asynchronously, you can start and abort one or more processes at will, all while continuing to interact with the main IDL process.
Note that once a process is initiated, the Execute button is desensitized. If it were not desensitized and you clicked Execute a second time (while the initial request was still being processed), execution would halt with the error, “The object’s associated IDL process is currently busy.” All child processes must finish executing one command before the next command is accepted. However, you can continue to interact with the parent process or other child processes while a child process executes a command asynchronously.
Note: You can also check status before calling the Execute method as described in Avoiding Busy Execution Errors.
Note: A second version of this example, idlbridge_demo_object.pro, provides the same functionality without the use of a callback procedure. This requires using timer events to continuously check the IDL_IDLBridge::Status method results. See Timer Events for more information on widget timers.
Tiling and Child Image Processing Example
This example displays a very large file (over 15 MB) and lets you explore the tiled image, zooming in or out and panning. It also includes a child process that applies the Roberts edge detection filter to the image data and creates a new 22 MB file. Since the filtering process occurs asynchronously in a child process, the tiling application can continue responding to requests for tile data and display the required tiles.
This example, idlbridge_tilingjp2_doc.pro, is located in the examples/doc/bridges subdirectory of the IDL distribution and calls idlbridge_img_processing.pro. Run the example procedure by entering idlbridge_tilingjp2 at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT idlbridge_tilingjp2.pro.
In this example, the Execute method of the IDL_IDLBridge object is passed a string that contains:
- The name of a procedure (idlbridge_img_processing.pro), which contains the image filtering code
- The JP2 filename, which is a procedure argument
The following lines transfer the variable value using SetVar and launch the idlbridge_img_processing.pro procedure in a child process (oBridge). The command is executed asynchronously due to the NOWAIT keyword.
oBridge->SetVar, 'filename', (*pState).jp2filename
oBridge->Execute, $
'idlbridge_img_processing, filename', /NOWAIT
When you run the tiling application (idlbridge_tilingjp2_doc.pro), click the Process Image button to begin filtering the data in the child process. When processing is complete, the filtered image is automatically displayed.
Note: This example relies on an image filename to determine what is to be filtered. If the image data were interactively updated through actions such as command line processing, you could pass the actual image data instead of the filename. You may pass scalar or array variables of numeric or string type (those allowed by IDL_IDLBridge::SetVar) to a child process.
Child Processing Distillation Example
This simple widget application (idlbridge_simple_doc.pro) launches the idlbridge_img_processing.pro procedure in a child process just as the previous tiling application does, but provides streamlined code and a simplified interface so that it is easier to follow execution and status retrieval for the IDL_IDLBridge object. Run the example and click Process Image to launch idlbridge_img_processing.pro in a child process.
This example, idlbridge_simple_doc.pro, is located in the examples/doc/bridges subdirectory of the IDL distribution and calls idlbridge_img_processing.pro. Run the example procedure by entering idlbridge_img_processing at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT idlbridge_img_processing.pro.
In this simplified example, it is easier to see how the progress bar (created in the child process) can be controlled from the parent IDL session. Typically, the progress bar base is destroyed when the image processing program finishes. However, if the user aborts the process or if an error halts execution, the end of the image processing program is never reached.
To kill the widget in the child process, you need the widget ID. You could create and update a widget ID variable in the child process, and then destroy the specific widget from a call in the parent process. However, this ties the two programs together. The parent program must know information that is internal to the child process.
Instead of requiring such a connection, you can use a common block. When you assign the value of the widget ID to a common block variable in the child process, you can access this value without having to pass it in from anywhere (either from the parent process or from the child process pState variable). This compartmentalizes processing. The parent process calls a routine in the child process to tell it that its operation was terminated abruptly by the primary process and that it should clean up any state related to it. The child process routine accesses the progress bar widget ID from the common block and cleans up. In the specified programs, notice the following relevant lines:
(*pState).oIDLBridge->Execute, $
'idlbridge_img_processing_abort_cleanup'
PRO idlbridge_img_processing_abort_cleanup
COMMON shareWidID, wChildBase
WIDGET_CONTROL, wChildBase, GET_UVALUE=pState
WIDGET_CONTROL, wChildBase, /DESTROY
PTR_FREE, pState
END
Image Processing Child Procedure
The image processing procedure (idlbridge_img_processing.pro), which is called from the tiling application and the simple widget interface, applies a Roberts filter to a given file. It also displays a progress bar to show the completion progress. While the IDL_IDLBridge object can return high level status (aborted, completed, halted with error, executing or idle) for a child process that is executing a command asynchronously, it does not give any indication of what percentage of a child process has been completed.
This image processing program updates the progress bar display throughout child process execution to provide more granular user feedback. Such a display could also provide feedback in a synchronous child process where status information is not available.
This example, idlbridge_img_processing.pro, is located in the examples/doc/bridges subdirectory of the IDL distribution. Run the example procedure by entering idlbridge_img_processing at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT idlbridge_img_processing.pro. It is designed to be called from the previously mentioned tiling application or simple widget interface, but can be run independently once the required JP2 file has been created.
You can use a child process executing a command asynchronously much like a batch file—one that completes processing tasks without any interaction. In such cases, a user interface that relays progress isn’t needed. However, if your application completes background processing that you care about, status updates are useful. This example shows one option for displaying such information if needed.
Version History
See Also