The IDLAsyncBridgeJob class represents a unit of work to be done at some point in the future inside an IDL_IDLBridge. This class allows you to specify a single IDL command to be executed inside the bridge when this job is run. It also allows you to specify an optional IDL command to be executed inside the bridge when it is first initialized. Submitting these to an IDLAsyncQueue will allow them to be performed as resources become available.

Superclasses

Examples

; Download a few 'images of the day' from eoimages.gsfc.nasa.gov
mainURL = 'https://eoimages.gsfc.nasa.ghtml/images/imagerecords/149000/'
 
; List of files to download
files = [ '149538/cropsfranceground_gedi_2019_lrg.jpg', $
          '149554/antarctic_meteorites_2022_lrg.jpg', $
          '149502/salardeuyuni_tmo_202250_lrg.jpg', $
          '149518/northatlantic_alan_04_lrg.jpg' ]
 
; create a folder in the temp folder for the local files
localFolder = FilePath(datasetName, /TMP)
if (~File_Test(localFolder)) then File_MkDir, localFolder
 
; construct IDLAsyncJoin object to use for waiting on all jobs to complete
oJoin = IDLAsyncJoin()
; construct IDLAsyncQueue to manage parallel execution of jobs
oQueue = IDLAsyncQueue(CONCURRENCY=6)
; create object array to hold all jobs
jobs = ObjArr(N_Elements(files))
 
; Define compound command to execute in the bridge.
; This command creates an IDLnetURL object, then calls its Get() method,
; passing in the remote URL and local filename to use.  The command must
; also delete the IDLnetURL variable to avoid an error when the
; IDLAsyncBridgeJob tries to call IDL_IDLBridge::GetVar() on an object
; variable.
; An alternate command that works using a procedure is:
;   bridgeCmd = 'download_S3_URL, S3_URL=s3Url, LOCAL_FILE=localFile'
bridgeCmd = 'u = IDLnetURL() & !null = u.Get(URL=s3Url, FILE=localFile) & Obj_Destroy, u & delvar, u'
 
; construct a unique job for each remote file to download
foreach file, files, i do begin
  remote = mainURL + file
  local = FilePath(File_Basename(file), ROOT=localFolder)
  ; construct IDLAsyncBridgeJob to execute compound command,
  ; passing in required variables and join object
  jobs[i] = IDLAsyncBridgeJob(bridgeCmd, $
                              s3Url=remote, $
                              localFile=local, $
                              JOIN=oJoin)
endforeach
 
; submit all the jobs to the queue for execution
oQueue.SubmitJob, jobs
; wait for all jobs to be done
oJoin.WaitForJoin

Syntax

Result = IDLAsyncBridgeJob(Command [, JOIN=IDLAsyncJoin] [, Variables=Value])

You can pass in one or more input variables to the bridge before executing COMMAND. The keyword used will be the name of the variable in the bridge. Note that objects must be dehydrated before passing in here, as IDL_IDLBridge::SetVar will not handle them correctly.

Arguments

Command

The value used for the COMMAND property.

Keywords

JOIN (optional)

An IDLAsyncJoin object that is passed to the IDLAsyncJob base class Init() method for handling.

 

Specify keywords using the names of the variables you want to send to the bridge.

Methods

Properties

IDLAsyncBridgeJob inherits all properties from IDLAsyncJob.

COMMAND (Get, Init)

A scalar string of IDL code to be executed inside the bridge when this job is executed. Make sure that the command does not create any objects, as IDL_IDLBridge::GetVar will not handle them correctly. Either dehydrate and serialize output objects, or use DELVAR to delete them.

INIT_COMMAND (optional)

A scalar string of IDL code to be executed inside the bridge when it is initialized.

IDLAsyncBridgeJob::GetReturnValue

The IDLAsyncBridgeJob::GetReturnValue method is an override of the IDLAsyncJob interface method. This procedure retrieves one or more named variables from the bridge after the remote work has finished executing. Note that remote objects must be dehydrated before being requested here, as IDL_IDLBridge::GetVar will not handle them correctly. If the variable name is unknown, or the job has not successfully completed execution, then the value passed into this method is unchanged.

Syntax

IDLAsyncBridgeJob.GetReturnValue [, Variables=Value]

Arguments

None

Keywords

Specify keywords using the names of the variables you are retrieving from the bridge.

ERROR

If the job fails, this will contain the error message generated by executing COMMAND inside the bridge.

If the job succeeds, this will be an empty string, unless the COMMAND resulted in an ERROR variable being generated in the bridge, in which case it will have the appropriate value.

IDLAsyncBridgeJob::OnStart

The IDLAsyncBridgeJob::OnStart method is an implementation override of the IDLAsyncJob callback invoked on this job by the Start event handler. The basic sequence of operations follows:

  • Create the IDL_IDLBridge.
  • Call IDL_IDLBridge::Execute with the INIT_COMMAND, if it was set.
  • Iterate over the variables passed as keywords into Init() and call IDL_IDLBridge::SetVar on each.
  • Set up the callback for bridge events.
  • Call IDL_IDLBridge::Execute with COMMAND.
  • Handle bridge events, to invoke the OnDone callback on itself.
  • If the bridge is successful in executing COMMAND, then all remote variables that were not passed into this object on construction are retrieved from the bridge, and it is destroyed to release any licenses it used. These remote variables must not be objects, as IDL_IDLBridge::GetVar will not handle them correctly.

Syntax

IDLAsyncBridgeJob.OnStart

Arguments

None

Keywords

None

Version History

8.7

Introduced

See Also

IDLAsyncJob, IDLAsyncJoin, IDLAsyncQueue, IDL_IDLBridge::SetVar, IDL_IDLBridge::Execute