The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
LSF_Base_0.07
River stage zero No dependents
++
/ LSF::Base

NAME

LSF::Base - Object oriented Perl extension for use with the Platform Computing Corporation's LSF.

SYNOPSIS

  use LSF::Base;
  
  $base = new LSF::Base;
  
  #Cluster configuration

  $info = $base->info or die $@;
  
  @resources = $info->resTable;
  $res = $resources[0];

  $name  = $res->name;
  $desc  = $res->des;
  $vt    = $res->valueType; # 0,1,2 (BOOLEAN, NUMERIC, STRING)
  $ot    = $res->orderType; # 0,1,2 (INCR, DECR, NA)
  $flags = $res->flags; # RESF_BUILTIN | RESF_*
  $int   = $res->interval; #seconds

  $nRes    = $info->nRes;
  @resTable= $info->resTable;
  @types   = $info->hostTypes;
  @models  = $info->hostModels;
  @archs   = $info->hostArchs;
  @narch   = $info->modelRefs;
  @factors = $info->cpuFactor;
  $n_index = $info->numIndx;
  $n_usr   = $info->numUsrIndx;

  $myhost = $base->getmyhostname;

  $cluster = $base->getclustername;
  
  $master  = $base->getmastername;
  
  $type    = $base->gethosttype($host);

  $model   = $base->gethostmodel($host);
  
  $factor  = $base->gethostfactor($host);
  
  $factor  = $base->getmodelfactor($model);

  @hosts = qw(skynet alpha60 wopr ghostwheel);
  # passing in @hosts restricts the results to the listed
  # hosts. 
  
  @hostinfo = $base->gethostinfo($resreq, \@hosts, $options);
  
  #return information on all hosts.
  @hostinfo = $base->gethostinfo($resreq, NULL, $options);
  
  $hi = $hostinfo[0];

  $name      = $hi->hostName;
  $type      = $hi->hostType;
  $model     = $hi->hostModel;
  $factor    = $hi->cpuFactor;
  $max_cpus  = $hi->maxCpus;
  $max_mem   = $hi->maxMem;
  $max_swap  = $hi->maxSwap;
  $max_tmp   = $hi->maxTmp;
  $ndisks    = $hi->nDisks;
  @resources = $hi->resources;
  $windows   = $hi->windows;
  @threshold = $hi->busyThreshold;
  $is_server = $hi->isServer;
  $licensed  = $hi->licensed;
  $rex_pri   = $hi->rexPriority;
  $lic_feat  = $hi->licFeaturesNeeded;

  @params = qw( LSF_SERVERDIR LSF_CONFDIR LSF_SERVER_HOSTS LSF_MANDIR); 
  %env = $base->readconfenv(\@params, $ENV{LSF_ENVDIR});
  
  #load information and placement functions

  @hostload = $base->load($resreq, $numhosts, $options, $fromhost );
  
  @hostload = $base->loadofhosts( $resreq, $numhosts, $options, $fromhost, \@hosts);
  
  $hl = $hostload[0];

  $name = $hl->hostName;
  @status = $hl->status

  $bool = ISUNAVAIL(\@status);
  $bool = ISBUSY(\@status);
  $bool = ISBUSYON(\@status,$index);
  $bool = ISLOCKEDU(\@status);
  $bool = ISLOCKEDW(\@status);
  $bool = ISLOCKED(\@status);
  $bool = ISRESDOWN(\@status);
  $bool = ISSBDDOWN(\@status);
  $bool = ISUNLICENSED(\@status);
  $bool = ISOK(\@status);
  $bool = ISOKNRES(\@status);
 
  @where = $base->placereq( $resreq, $number, $options, $fromhost);
  
  @where = $base->placeofhosts( $resreq, $number, $options, $fromhost, \@hosts);
  
  $place{alpha60} = 3;
  $place{skynet} = 2;

  $base->loadadj($resreq, \%place) or die $@;
   
  #Task list manipulation

  $resreq = $base->resreq($task);
 
  ($bool, $resreq) = $base->eligible($task, $mode);
  
  $base->insertrtask($task);
  
  $base->insertltask($task);

  $base->deletertask($task);
   
  $base->deleteltask($task);
  
  @remote = $base->listrtask($sortflag);
   
  @local = $base->listltask($sortflag);
    
  # Remote Execution and task control functions

  $ports = $base->initrex($numports, $options); # or KEEPUID
   
  $base->connect($hostname) or die $@;
  
  $bool = base->isconnected($hostname);
    
  @connections = $base->findmyconnections;
 
  $base->rexecv($host, \@argv, $options) or die $@;
    
  $base->rexecve($host, \@argv, $options, \@envp) or die $@;
    
  $tid = $base->rtask($host, \@argv, $options);
  
  $tid = $base->rtaske($host, \@argv, $options, \@env);
  
  ($tid, $ru) = $base->rwait($options);
  $status = $?;
  
  $ru = $base->rwaittid($tid, $options);
  $status = $?;
    
  $u_sec = $ru->utime_sec;
  $u_usec = $ru->utime_usec;
  $s_sec = $ru->stime_sec;
  $s_usec = $ru->stime_usec;
  $maxrss = $ru->maxrss;
  $ixrss = $ru->ixrss;
  $idrss = $ru->idrss;
  $minflt = $ru->minflt;
  $majflt = $ru->majflt;
  $nswap = $ru->nswap;
  $inblock = $ru->inblock;
  $outblock = $ru->outblock;
  $msgsnd = $ru->msgsnd;
  $msgrcv = $ru->msgrcv;
  $nsignals = $ru->nsignals;
  $nvcsw = $ru->nvcsw;
  $nivcsw = $ru->nivcsw;

  $base->rkill($tid, $signal) or die $@;
    
  $base->rsetenv($host, \@env) or die $@;
    
  $base->chdir($host, $path) or die $@;
    
  $base->stdinmode($remote) or die $@;
    
  @tids = $base->getstdin($on, $max);
    
  $base->setstdin($on, \@tids) or die $@;
    
  $base->stoprex or die $@;
  
  $base->donerex or die $@;
  
  $socket = $base->conntaskport($tid);
  
  # Remote file operations

  $rfd = $base->ropen($host, $filename, $flags, $mode) or die $@;
   
  $base->rclose($rfd) or die $@;
  
  $bytes = $base->rwrite($rfd, $buf, $len);
    
  $bytes = $base->rread($rfd, $buf, $len );
  
  $offset = $base->rlseek($rfd, $offset, $whence );
  
  @stat = $base->rfstat($rfd);
 
  @stat = $base->rstat($host, $path);
    
  $host = $base->getmnthost($file);
    
  $host = $base->rgetmnthost($host, $file);
  
  #if LSF_VERSION < 9
  
  $base->rfcontrol($option, \@arg);
  #Controls the behavior of remote file operations. $option is either 
  #RF_CMD_MAXHOSTS or RF_CMD_TERMINATE. @arg should be one or more of the
  #following: REXF_USEPTY,REXF_CLNTDIR, REXF_TASKPORT, REXF_SHMODE, 
  #REXF_TASKINFO, REXF_REQVCL, REXF_SYNCNIOS, REXF_TTYASYNC, REXF_STDERR.
  
  #else 
  $base->rfcontrol($option, \@arg) or die $@;
  #Controls the behavior of remote file operations.$option is either 
  #RF_CMD_RXFLAGS or RF_CMD_MAXHOSTS. @arg is the same with that of above.
  
  #endif
  
  $base->lockhost($duration) or die $@;
    
  $base->unlockhost() or die $@;
    
  $base->limcontrol($hostname, $opcode) or die $@;
    
  $base->rescontrol($hostname, $opcode, $data) or die $@;
  
  $base->perror($message);
   
  $base->sysmsg;
    
  $base->errno;
    
  $base->errlog(FILE, $msg);
  
  $base->fdbusy($fd);

DESCRIPTION

LSF provides basic load sharing functionality consisting of the following services: cluster configuration information, load information and placement advice, task list manipulation, remote execution and task control, remote file operations, administration, and error handling.

This library is designed to be used with LSF version 7.0 Update 2. Please see the "LSF Programmer's Guide" and the LSF man pages for detailed documentation of this API.

The data structures used in the API have been wrapped in Perl objects for ease of use. The functions set $@ and $? where appropriate, or you can use the lserrno, sysmsg, and perror functions if you want.

The Perl version of this API has been modified to some extent to act more "Perlish" than the straightforward C API. For instance, return values have been changed to more closely match what a Perl programmer expects from a function. Other deviations from the original are noted in the documentation.

$info = $base->info;

This routine returns a pointer to an lsInfo structure, which contains complete load sharing configuration information. This information includes the name of the cluster, the name of the current cluster master host, the set of defined resources, the set of defined host types and models, the CPU factors of the host models, and all load indices (resTable[0] through resTable[numIndx - 1]), including the site defined external load indices (resTable[MAX + 1] through resTable[MAX + numUsrIndx]).

$myhost = $base->getmyhostname;

This routine returns the name used throughout LSF to represent the local host.

$cluster = $base->getclustername;

This routine returns the name of the local load sharing cluster.

$master = $base->getmastername;

This routine returns the name of the host running the local load sharing cluster's master LIM.

$type = $base->gethosttype(host);

This routine returns the type of the specified host.

$model = $base->gethostmodel(host);

This routine returns the model of the specified host.

$factor = $base->gethostfactor(host);

This routine returns a pointer to a floating point number that contains the CPU factor of the specified host.

$factor = $base->getmodelfactor(model);

This routine returns the CPU normalization factor of the specified host model. model can be obtained by calling $base->gethostmodel.

@hostinfo = $base->gethostinfo(resreq, hosts, options);

This routine returns an array of hostInfo data structures. resreq specifies resource requirements that a host must satisfy; hosts is the reference of array and gives a list of hosts or clusters whose information is returned if they satisfy the requirements in resreq. if hosts is undefined, all hosts known to LSF that satisfy the requirements in resreq are returned. options should be zero or one or more of the following: EXACT, OK_LOLY, NORMALIZE, LOCALITY, LGNORE_RES, DFT_FROMTYPE, EFFECTIVE. Each entry contains information about one host, including the host type, the host model, its CPU normalization factor, the number of CPUs, its maximum memory, swap and tmp space, number of disks, the resources available on the host, the run windows during which the host is available for load sharing, the busy thresholds for the host, whether the host is a LSF server, and the default priority used by the RES for remote tasks executing on that host. The windows field will be set to "-" if the host is always open. The busyThreshold field is an array of floating point numbers specifying the load index thresholds that LIM uses to consider a host as busy. The size of the array is indicated by the numIndx field.

%env = $base->readconfenv(paramList, confPath);

This routine reads the LSF configuration parameters from the confPath/lsf.conf. If confPath is NULL, the LSF configurable parameters are read from the ${LSF_ENVDIR-/etc}/lsf.conf file. The input paramList is a reference of array of (LSF_SERVERDIR LSF_CONFDIR LSF_SERVER_HOSTS LSF_MANDIR).

@hostload = $base->load(resreq, numhosts, options, fromhost);

This routine returns an array of hostLoad data structures. resreq is a character string describing resource requirements. numhosts initially contains the number of hosts requested. options is the same as that of $base->gethostinfo(). fromhost is the name of the host from which a task might be transferred. This parameter affects the host selection in such a way as to give preference to fromhost if the load on other hosts is not much better. If fromhost is undefined, the local host is assumed.

@hostload = $base->loadofhosts(resreq, numhosts, options, fromhost, hosts);

This routine returns the dynamic load information of qualified hosts. The parameters are the same as that of $base->load(). hosts is an array of listsize host or cluster names. If undefined, only load information about hosts in this list will be returned.

@where = $base->placereq(resreq, number, options, fromhost);

This routine returns the most suitable host() for the task() with regards to current load conditions and the task's resource requirements. resreq is a resource requirement expression that characterizes the resource needs of a single task. number is the number of hosts requested. options is the same as $base->load(); fromhost is the host from which the task originates when LIM makes the placement decision. If fromhost is undefined, the local host is assumed.

@where = $base->placeofhosts(resreq, number, options, fromhost, hosts);

This routine returns the most suitable host() for the task() from a set of candidate hosts with regards to current load conditions and the task's resource requirements. The first four parameters are the same as that of $base->placereq, hosts specifies a list of candidate hosts from which $base->placeofhosts() can choose suitable hosts.

$base->loadadj(resreq, place);

This routine sends a load adjustment request to LIM after the execution host or hosts have been selected outside the LIM by the calling application. resreq is a resource requirement expression (that can be NULL) that describes the resource requirements for which the load must be adjusted. place is a hash variable. The key is a hostname and the value is the number of tasks on the host.

$resreq = $base->resreq(task);

This routine searches a remote task list and returns the resource requirements. task is the name of the task being sought.

($bool, $resreq) = $base->eligible(task, mode);

This routine checks to see if a task is eligible for remote execution. task is being checked to see if it can be remotely executed. mode is LSF_LOCAL_MODE or LSF_REMOTE_MODE. If mode is LSF_LOCAL_MODE, the routine searches through the remote task lists to see if the name of task is on a list. If found, the task is considered eligible for remote execution, otherwise the task is considered ineligible. if mode is LSF_REMOTE_MODE, the routine searches through the local task lists to see if taskname is on a list. If found, the task is considered ineligible for remote execution, otherwise the task is considered eligible.

$base->insertrtask(task);

This routine adds a specified task to the remote task list. task is a character string containing the name of the task to be inserted .

$base->insertltask(task);

This routine adds the specified task to the local task list. task is a character string containing the name of the task to be inserted.

$base->deletertask(task);

This routine deletes a specified task from the remote task list. task is a character string containing the name of the task to be deleted.

$base->deleteltask(task);

This routine deletes a specified task from the local task list. task is a character string containing the name of the task to be deleted.

@remote = $base->listrtask(sortflag);

This routine returns the contents of the user's remote task list. If sortflag is non-zero, then the returned task list is sorted alphabetically. Usually, sortflag is set to 1.

@local = $base->listltask(sortflag);

This routine retruns the contents of the user's local task list. sortflag is the same as the one of $base->listrtask.

$ports = $base->initrex(numports, options);

This routine initializes the LSF library for remote execution. options is usually set to 0.

$base->connect(hostname);

This routine sets up an initial connection with the Remote Execution Server (RES) on a specified remote host. hostname that is set up with a Remote Execution Server.

$bool = base->isconnected(hostname);

This routine tests whether the specified host is currently connected with the application. hostname is the name of target host. When it returns 1, it means function was successful, 0 means the function failed.

@connections = $base->findmyconnections;

This routine finds established connections to hosts.

$base->rexecv(host, argv, options);

This routine executes a program on a specified remote host. host is the remote host where the program is executed. argv is the program being used. options is constructed by ORing flags from the following list: REXF_USEPTY, REXF_CLNTDIR, REXF_TASKPORT, REXF_SHMODE.

$base->rexecve(host, argv, options, envp);

This routine is the same as $base->rexecv() except that it provides the support of setting up a new environment specified by the string array envp. When envp is undefined, it means using the remote RES server's cached environment. Otherwise it uses the new one. argv and options are the same as the ones of $base->rexecv().

$tid = $base->rtask(host, argv, options);

This routine starts a remote task on a specified host. host is the remote host where the program is executed. argv is the program being used. options should be one or more of the following: REXF_USEPTY, REXF_CLNTDIR, REXF_TASKPORT, REXF_SHMODE, REXF_TASKINFO, REXF_REQVCL, REXF_SYNCNIOS, REXF_TTYASYNC, REXF_STDERR.

$tid = $base->rtaske(host, argv, options, env);

This routine is the same as $base->rtask() except that it provides the support of setting up a new environment specified by the string array envp. When envp is undef, it means using the remote RES server's cached environment. Otherwise it uses the new one. Other arguments are the same as the ones of $base->rtask().

($tid, $ru) = $base->rwait(options);

This routine collects the status of a remote task started by $base->rtask() or $base->rtaske(). options should be WNOHANG or WUNTRACED, if it specified as 0, and there is at least one remote child, then the calling host is blocked until a remote child exits. If options is specified to be WNOHANG, the routine checks for any exited (remote) child and returns immediately. $ru is a pointer to the struct of rusage. $tid returns the remote task ID, if $tid was -1, the function failed.

$ru = $base->rwaittid(tid, options);

This routine provides support for collecting the status of a specified remote task. tid is the ID of the remote task being accessed. if options is set to 0, and there is at least one remote task, the calling host is blocked until the specific task exits. If options is WNOHANG (non-blocking), it reads the child's status if the child is dead, otherwise it returns immediately with 0. If the status of the child is successfully read, the remote task ID is returned. $ru is the structure where the resource usage information of the exited child is stored.

$base->rkill(tid, signal);

This routine sends the signal to the remote task $tid and all its children that belong to the same UNIX process group. tid is the remote task ID returned by $base->rtask() or $base->rtaske().

$base->rsetenv(host, env);

This routine sets up environment variables on a remote host. host is the remote host upon which the environment is being set. env is a pointer to an array of strings of the form variable=value.

$base->chdir(host, path);

This routine sets the application's working directory on the remote host to the directory specified by path. host is the remote host containing the client directory. path is the full pathname of a valid directory on the remote host.

$base->stdinmode(remote);

This routine allows an application program to query and specify how stdin is assigned to remote tasks on a local application. If remote is non-zero, then the application will not read subsequent standard input, and the remote children will read standard input. This mode of operation is called the remote stdin mode. Remote stdin mode is the default. In remote stdin mode, standard input is read by the Network I/O Server (NIOS) and forwarded to the appropriate remote tasks. If remote is zero, then the application reads the subsequent standard input, and it is not forwarded to remote children. This mode of operation is called the local stdin mode.

@tids = $base->getstdin(on, max);

This routine allows an application program to query and specify how stdin is assigned to remote tasks. If on is non-zero, the task IDs of the remote tasks that are enabled to receive standard input are stored in tidlist. If it is zero, then the IDs of remote tasks whose standard input is disabled are returned. The ID of a task is assigned by the LSLIB when $base->rtask() is called. max is the size of the remote IDs list; these remote tasks are enable to receive standard input.

$base->setstdin(on, tids);

This routine allows an application program to query and specify how stdin is assigned to a specific subset of remote tasks. If on is non-zero and the current stdin mode is remote, then the tasks given by tidlist receive the standard input. If it is zero, the tasks will not receive standard input. tids gives the list of task IDs of the remote tasks to be operated upon.

$base->stoprex;

This routine stops the Networks I/O Server and restores the local tty environment.

$base->donerex;

This routine kills the Network I/O server (NIOS) and restores the tty environment before a remote execution connection is closed.

$socket = $base->conntaskport(tid);

This routine connects a socket to the task port that was created by the remote RES for the remote task tid, tid is returned by an $base->rtask() or $base->rtaske().

$rfd = $base->ropen(host, filename, flags, mode);

This routine opens a file on a remote host. host is the host where the file to be opened is located. filename is the file to be opened. flags is one or more of the following: O_CREAT, O_WRONLY, O_RDONLY.

$base->rclose(rfd);

This routine performs a close operation on a file on a remote host. rfd is the references of the file that is to be closed, returned by $base->ropen().

$bytes = $base->rwrite(rfd, buf, len);

This routine performs a write operation on a file on a remote host.

$bytes = $base->rread(rfd, buf, len );

This routine performs a read operation on a file on a remote host.

$offset = $base->rlseek(rfd, offset, whence );

This routine performs a seek operation on a file on a remote host.

@stat = $base->rfstat(rfd);

This routine obtains information about a file located on a remote host.

@stat = $base->rstat(host, path);

This routine obtains information about a file located on a remote host. host is the remote host containing the file to be analyzed. path is the path of the file.

$host = $base->getmnthost(file);

This routine returns the name of the file server containing a specific file. file is the relative or absolute path name for the file server.

$host = $base->rgetmnthost(host, file);

This routine obtains the name of the file server that exports a specified file system. host is the host containing the file. file is the file to be accessed.

$base->rfcontrol(option, arg);

This routine controls the behavior of remote file operations. option is either RF_CMD_MAXHOSTS or RF_CMD_TERMINATE. arg should be one or more of the following: REXF_USEPTY,REXF_CLNTDIR, REXF_TASKPORT, REXF_SHMODE, REXF_TASKINFO, REXF_REQVCL, REXF_SYNCNIOS, REXF_TTYASYNC, REXF_STDERR.

$base->lockhost(duration);

This routine locks the local host for a specified number of seconds. duration is the number of seconds the local host is locked. 0 seconds locks a host indefinitely.

$base->unlockhost();

This routine unlocks a locked local host.

$base->limcontrol(hostname, opcode);

This routine shuts down or reboots a host's LIM. hostname specifies the host to be controlled. opcode is either LIM_CMD_SHUTDOWN or LIM_CMD_REBOOT.

$base->rescontrol(hostname, opcode, data);

This routine controls and maintains the Remote Execution Server. hostname is the host to be controlled. The support opcode value are: RES_CMD_REBOOT, RES_CMD_SHUTDOWN, RES_CMD_LOGOFF and RES_CMD_LOGON. data is optionally used with RES_CMD_LOGON to specify a CPU time threshold in msec, so that RES will log resource information only for tasks that consumed more than the specified CPU time.

$base->perror(message);

This routine prints LSF error messages. message is standard output error string.

$base->sysmsg;

This routine obtains LSF error messages.

$base->errno;

This routine returns lsberrno correctly.

$base->errlog(FILE, msg);

This routine logs error messages. FILE is a file handle. msg is error message.

$base->fdbusy($fd);

This routine tests if a specified file descriptor is in use or reserved by LSF. fd is the file descriptor to test.

AUTHOR

Paul Franceus, Capita Technologies, Inc., paul@capita.com

MODIFIER

ISV Team, Platform Computing Corporation, support@platform.com

SEE ALSO

perl(1), LSF::Batch, LSF Programmer's guide, lslib(3), LSF man pages for each function