TABLE OF CONTENTS

::pwtk::tpool::job

SYNOPSIS

    method job {args} {

USAGE

   $obj job ?-delay MS? SCRIPT

DESCRIPTION

This method submits a job to the '$obj' thread-pool.

If -delay option is specified, it waits for 'MS' milliseconds before the job is submitted. This is typically needed when jobs write and read from the same file (such as environ.in for ENVIRON) because otherwise file corruption can occur. This can typically happen only for the first concurrent submitted jobs because for later jobs, the probability of this happening is quite small as the previous jobs are unlikely to finish concurrently.

OPTIONS

ARGUMENTS

EXAMPLE

   $tp job {
       ::pwtk::run_fromXSF pw.x structure.xsf
   }

RETURN VALUE

SOURCE

        set narg 1
        set usage "?-delay ms? SCRIPT"
        set options {
            {delay.arg 0 "delay (in milliseconds) before submitting the job"}
        }
        ::pwtk::parseOpt_
        ::pwtk::checkOTypeStrict_ -delay $opt(delay) integer integer
        lassign $args script
        
        incr count

        if { $opt(delay) > 0 } {
            # add some small delay as a precaution if jobs write the same
            # file (for example, environ.in for ENVIRON calcs)
            
            after $opt(delay)
        }
        
        if { $type eq "thread" } {
            #
            # thread
            #
            set fullScript [::pwtk::propagate_dump hard_dump]\n$script
            #set fullScript $script; # N.B. not OK because we need a hard-dump; also tpool-t.test fails otherwise

            if { "-r" in $opts } {
                set log thread.$tpid.$count.log
                my print_ $script {} "Output of job-$count redirected to a log file:  $log\n"                
                lappend jobList [tpool::post $tpid [list ::pwtk::redirect_stdout_to $log $fullScript]]                
            } else {
                my print_ $script
                lappend jobList [tpool::post $tpid $fullScript]
            }
            
        } elseif { $type eq "bg" } {
            #
            # bg
            #
            set fullScript [::pwtk::propagate_dump]\n$script

            set oo [list -s -np -id $count -fid $tpid.$count]
            if { "-r" in $opts } {
                lappend oo -r
            }
            my print_ $script

            lappend jobList [tpool::post $tpid [list ::pwtk::tpool_bg_ {*}$oo $fullScript]]
            
        } else {
            #
            # remote
            #
            set fullScript [::pwtk::propagate_dump]\n$script

            if { $count <= $nworkers } {
                set host [lindex $hosts $count-1]
            } else {
                # wait for a worker to become available (if more workers become available, use the 1st one)
                set completed [lindex [tpool::wait $tpid $jobList] 0]

                # save the available host
                set host $workerHost($completed)

                # remove the completed job from jobList
                set jobList [lsearch -all -inline -not -exact $jobList $completed]                
            }
            my print_ $script $host
            
            # submit a remote job to an available worker

            set id [tpool::post $tpid [list ::pwtk::remote -fg -np -id $count -fid $tpid.$count {*}$opts $host $fullScript]]
            set workerHost($id) $host
            lappend jobList $id
        }

        # return this job ID
        return [lindex $jobList end]
    }