ls_loadinfo

Returns the requested load indices of the hosts that satisfy specified resource requirements.

This routine returns the dynamic load information of qualified hosts.

ls_loadinfo returns the requested load indices of the hosts that satisfy the specified resource requirements. The result of this call is an array of hostLoad data structures as defined in <lsf/lsf.h>. The status component of the hostLoad structure is an array of integers. The high order 16 bits of the first int are used to mark the operation status of the host. Possible states defined in <lsf/lsf.h> are as follows: status_ls_load.

ls_load returns all load indices. The result of this call is an array of hostLoad data structures as defined in <lsf/lsf.h>. The status component of the hostLoad structure is an array of integers. The high order 16 bits of the first int are used to mark the operation status of the host. Possible states defined in <lsf/lsf.h> are as follows: status_ls_load.

The low order 16 bits of the first int are reserved. The other int() of the status array is used to indicate the load status of the host. If any of these bits is set, then the host is considered to be busy (overloaded). Each bit (starting from bit 0) in int() represents one load index that caused the host to be busy. If bit i is set then the load index corresponding to li[i] caused the host to be busy. An int can be used to for 32 load indices. If number of load indices on the host, both built-in and user defined, are more than 32, more than one int will be used.

Programmers can use macros to test the status of a host. The most commonly used macros include:

• LS_ISUNAVAIL(status)
• LS_ISBUSY(status)
• LS_ISBUSYON(status, index)
• LS_ISLOCKEDU(status)
• LS_ISLOCKEDW(status)
• LS_ISLOCKED(status)
• LS_ISRESDOWN(status)
• LS_ISUNLICENSED(status)
• LS_ISOK(status)

In the hostLoad data structure, the li vector contains load information on various resources on a host. The elements of the load vector are determined by the namelist parameter.

The returned hostLoad array is sorted according to the order section of the resource requirements, resreq (or, if not specified, the 1-minute average CPU queue length and paging rate), with the lightest loaded host being the first.

hostlist is an array of listsize host or cluster names. If not NULL, then only load information about hosts in this list will be returned.

#include <lsf/lsf.h>

struct hostLoad *ls_loadinfo(char *resreq, int *numhosts, int options, char *fromhost, char **hostlist, int listsize, char ***namelist)

Parameters:

	*resreq	resreq is a char string describing resource requirements. Only the load vectors of the hosts satisfying the requirements will be returned. If resreq is NULL, the load vectors of all hosts will be returned.
	*numhosts	numhosts is the address of an int which initially contains the number of hosts requested. If *numhosts is 0, request information on as many hosts as satisfy resreq. If numhosts is NULL, requests load information on one (1) host. If numhosts is not NULL, then *numhosts will contain the number of hostLoad records returned on success.
	options	options is constructed from the bitwise inclusive OR of zero or more of the following flags, as defined in <lsf/lsf.h>: options_ls_load.
	*fromhost	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 NULL, the local host is assumed.
	**hostlist	An array of listsize host or cluster names.
	listsize	listsize gives the number of host or cluster names in hostlist.
	***namelist	namelist is an input/output parameter. On input it points to a null-terminated list of names of indices whose values will be returned in the li vector for each host selected. Setting namelist to point to NULL returns all indices. On return it points to a null-terminated list of the names of the indices returned in the li load vector for each host. Each element of the load vector is a floating point number between 0.0 and INFINIT_LOAD (defined in lsf.h). The index value is set to INFINIT_LOAD to indicate an invalid or unknown value for an index. The indices in the li vector are ordered such that li[i] contains the value of index namelist[i]. If index namelist[i] is causing the host to be busy, then LS_ISBUSYON(status, i) will be TRUE. When the input namelist is NULL the output namelist is ordered such that the li vector can be indexed using constants defined in <lsf/lsf.h> as listed below: index_ls_loadinfo.

Data Structures:

hostLoad

Define Statements:

status_ls_load
options_ls_load
index_ls_loadinfo

Returns:

struct hostLoad *:An array of hostLoad struct containing load information.
Function was successful.

NULL
Function failed.

Errors:

Systems that conform to the Single UNIX specification are not required to detect error conditions for this function.

Equivalent line commands:

none

Files:

$LSF_CONFDIR/lsf.shared
$LSF_CONFDIR/lsf.cluster.cluster_name

See also:

ls_load

ls_loadofhosts