NAME
LSF::Base - Object oriented Perl extension for use with the Platform Computing Corporation's Load Sharing Facility (LSF) Base product.
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 Base 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 gives a list of hosts or clusters whose information is returned if they satisfy the requirements in resreq. ifhosts
is undef, all hosts known to LSF that satisfy the requirements inresreq
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. IfconfPath
is NULL, the LSF configurable parameters are read from the ${LSF_ENVDIR-/etc}/lsf.conf file. The inputparamList
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 tofromhost
if the load on other hosts is not much better. iffromhost
is undef, 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 not undef, 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. iffromhost
is undef, 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 (which 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. Ifmode
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. ifmode
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 inesrted . - $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 inesrted. - $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
usually is 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. Returns 1 means function was successful, 0 is 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
. Whenenvp
is undef, it means using the remote RES server's cached environment, otherwise using the new one.argv
andoptions
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
. Whenenvp
is undef, it means using the remote RES server's cached environment, otherwise using 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. Ifoptions
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. ifoptions
is set to 0, and there is at least one remote task, the calling host is blocked until the specific task exits. Ifoptions
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 formvariable=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 sllows 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. Ifremote
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 supportopcode
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