Knowledge Center         Contents    Previous  Next    
Platform Computing Corp.

lsb_queueinfo()

Returns information about batch queues.

DESCRIPTION

lsb_queueinfo() gets information about batch queues. See lsb.queues for more information about queue parameters.

SYNOPSIS

#include <lsf/lsbatch.h> 
struct queueInfoEnt *lsb_queueinfo(char **queues,  
                     int *numQueues, char *hosts, char *users,  
                     int options) 
struct queueInfoEnt { 
    char   *queue; 
    char   *description; 
    int    priority; 
    short  nice; 
    char   *userList; 
    char   *hostList; 
    char   *hostStr; 
    int    nIdx; 
    float  *loadSched; 
    float  *loadStop; 
    int    userJobLimit; 
    float  procJobLimit; 
    char   *windows; 
    int    rLimits[LSF_RLIM_NLIMITS]; 
    char   *hostSpec; 
    int    qAttrib; 
    int    qStatus; 
    int    maxJobs; 
    int    numJobs; 
    int    numPEND; 
    int    numRUN; 
    int    numSSUSP; 
    int    numUSUSP; 
    int    mig; 
    int    schedDelay; 
    int    acceptIntvl; 
    char   *windowsD; 
    char   *nqsQueues; 
    char   *userShares; 
    char   *defaultHostSpec; 
    int    procLimit; 
    char   *admins; 
    char   *preCmd; 
    char   *postCmd; 
    char   *requeueEValues; 
    int    hostJobLimit; 
    char   *resReq; 
    int    numRESERVE; 
    int    slotHoldTime; 
    char   *sndJobsTo; 
    char   *rcvJobsFrom; 
    char   *resumeCond; 
    char   *stopCond; 
    char   *jobStarter; 
    char   *suspendActCmd; 
    char   *resumeActCmd; 
    char   *terminateActCmd; 
    int    sigMap[LSB_SIG_NUM]; 
    char   *preemption; 
    int    maxRschedTime; 
    int    numOfSAccts; 
    struct shareAcctInfoEnt*  shareAccts; 
    char   *chkpntDir; 
    int    chkpntPeriod; 
    int    imptJobBklg; 
    int    defLimits[LSF_RLIM_NLIMITS]; 
    int    chunkJobSize; 
    int    minProcLimit; 
    int    defProcLimit; 
    char   *fairshareQueues; 
    char   *defExtSched; 
    char   *mandExtSched; 
    int    slotShare; 
    char   *slotPool; 
    int    underRCond; 
    int    overRCond; 
    float  idleCond; 
    int    underRJobs; 
    int    overRJobs; 
    int    idleJobs; 
    int    warningTimePeriod; 
    char   *warningAction; 
    char   *qCtrlMsg;  
    char   *acResReq; 
    int    symJobLimit; 
    char   *cpuReq; 
    int    proAttr; 
    int    lendLimit; 
    int    hostReallocInterval; 
    int    numCPURequired; 
    int    numCPUAllocated; 
    int    numCPUBorrowed; 
    int    numCPULent; 
    int    schGranularity; 
    int    symTaskGracePeriod; 
    int    minOfSsm; 
    int    maxOfSsm; 
    int    numOfAllocSlots; 
    char *servicePreemption; 
    int    provisionStatus; 
    int    minTimeSlice;  
    char   *queueGroup; 
    int    numApsFactors; 
    struct apsFactorInfo *apsFactorInfoList; 
    struct apsFactorMap  *apsFactorMaps; 
    struct apsLongNameMap *apsLongNames; 
	int    maxJobPreempt; 
	int    maxPreExecRetry; 
	int    localMaxPreExecRetry; 
	    int    maxJobRequeue; 
	int    usePam; 
    int    cu_type_exclusive; 
    char   cu_str_exclusive; 
}; 
struct shareAcctInfoEnt { 
    char   *shareAcctPath; 
    int    shares; 
    float  priority; 
    int    numStartJobs; 
    float  histCpuTime; 
    int    numReserveJobs; 
    int    runTime; 
    int    shareAdjustment; 
}; 

PARAMETERS

**queues

An array of names of queues of interest.

*numQueues

The number of queue names.

To get information on all queues, set *numQueues to 0; *numQueues will be updated to the actual number of queues when this call returns.

If *numQueues is 1 and queues is NULL, information on the system default queue is returned.

*hosts

The host or cluster names. If hosts is not NULL, then only the queues that are enabled for the hosts are of interest.

*user

The name of user. If user is not NULL, then only the queues that are enabled for the user are of interest.

options

Reserved for future use; supply 0.

queueInfoEnt structure fields

The queueInfoEnt structure contains the following fields:

queue

The name of the queue.

description

Describes the typical use of the queue.

priority

Defines the priority of the queue. This determines the order in which the job queues are searched at job dispatch time: queues with higher priority values are searched first. (This is contrary to UNIX process priority ordering.)

nice

Defines the nice value at which jobs in this queue will be run.

userList

A blank-separated list of names of users allowed to submit jobs to this queue.

hostList

A blank-separated list of names of hosts to which jobs in this queue may be dispatched.

hostStr

Original HOSTS string in case "-" is used.

nIdx

The number of load indices in the loadSched and loadStop arrays.

loadSched & loadStop

The queue and host loadSched and loadStop arrays control batch job dispatch, suspension, and resumption.

The values in the loadSched array specify thresholds for the corresponding load indices. Only if the current values of all specified load indices of a host are within (below or above, depending on the meaning of the load index) the corresponding thresholds of this queue, will jobs in this queue be dispatched to the host. The same conditions are used to resume jobs dispatched from this queue that have been suspended on the host.

Similarly, the values in the loadStop array specify the thresholds for job suspension. If any of the current load index values of a host goes beyond a queue's threshold, jobs from the queue will be suspended.

For an explanation of the fields in the loadSched and loadStop arrays, see lsb_hostinfo().

userJobLimit

Per-user limit on the number of jobs that can be dispatched from this queue and executed concurrently.

procJobLimit

Per-processor limit on the number of jobs that can be dispatched from this queue and executed concurrently.

windows

A blank-separated list of time windows describing the run window of the queue. When a queue's run window is closed, no job from this queue will be dispatched. When the run window closes, any running jobs from this queue will be suspended until the run window reopens, when they will be resumed. The default is no restriction, or always open (i.e., 24 hours a day, seven days a week).

A time window has the format begin_time-end_time. Time is specified in the format [day:]hour[:minute], where all fields are numbers in their respective legal ranges: 0(Sunday)-6 for day, 0-23 for hour, and 0-59 for minute. The default value for minute is 0 (on the hour); the default value for day is every day of the week. The begin_time and end_time of a window are separated by `-', with no white space (i.e., blank or TAB) in between. Both begin_time and end_time must be present for a time window.

Note that this run window only applies to batch jobs; interactive jobs scheduled by the LSF Load Information Manager (LIM) are controlled by another set of run windows.

rLimits[LSF_RLIM_NLIMITS]

The per-process UNIX hard resource limits for all jobs submitted to this queue (see getrlimit() and lsb.queues). The default values for the resource limits are unlimited, indicated by -1. The constants used to index the rLimits array and the corresponding resource limits are listed below.

hostSpec

A host name or host model name. If the queue CPULIMIT or RUNLIMIT gives a host specification, hostSpec will be that specification. Otherwise, if defaultHostSpec (see below) is not NULL, hostSpec will be defaultHostSpec. Otherwise, if DEFAULT_HOST_SPEC is defined in the lsb.params file, (see lsb.params), hostSpec will be this value. Otherwise, hostSpec will be the name of the host with the largest CPU factor in the cluster.

qAttrib

The attributes of the queue. The bitwise inclusive OR of some of the following:

Q_ATTRIB_EXCLUSIVE

This queue accepts jobs which request exclusive execution.

Q_ATTRIB_DEFAULT

This queue is a default queue of LSF.

Q_ATTRIB_FAIRSHARE

This queue uses the FAIRSHARE scheduling policy. The user shares are given in userShares. (See below.)

Q_ATTRIB_PREEMPTIVE

This queue uses the PREEMPTIVE scheduling policy.

Q_ATTRIB_NQS

This is an NQS forward queue. The target NQS queues are given in nqsQueues. (See below.) For NQS forward queues, the hostList, procJobLimit, windows, mig and windowsD fields are meaningless.

Q_ATTRIB_RECEIVE

This queue can receive jobs from other clusters.

Q_ATTRIB_PREEMPTABLE

This queue uses a preemptable scheduling policy.

Q_ATTRIB_BACKFILL

This queue uses a backfilling policy.

Q_ATTRIB_HOST_PREFER

This queue uses a host preference policy.

Q_ATTRIB_NONPREEMPTIVE

This queue can't preempt any other another queue.

Q_ATTRIB_NONPREEMPTABLE

This queue can't be preempted from any queue.

Q_ATTRIB_NO_INTERACTIVE

This queue does not accept batch interactive jobs.

Q_ATTRIB_ONLY_INTERACTIVE

This queue only accepts batch interactive jobs.

Q_ATTRIB_NO_HOST_TYPE

No host type related resource name specified in resource requirement.

Q_ATTRIB_ IGNORE_DEADLINE

This queue disables deadline constrained resource scheduling.

Q_ATTRIB_ CHKPNT

Jobs may run as checkpointable.

Q_ATTRIB_ RERUNABLE

Jobs may run as rerunnable.

Q_ATTRIB_MC_FAST_SCHEDULE

Turn on multicluster fast scheduling policy.

Q_ATTRIB_ENQUE_INTERACTIVE_AHEAD

Push interactive jobs in front of other jobs in queue.

Q_MC_FLAG

Flags used by MultiCluster.

Q_ATTRIB_LEASE_LOCAL

Lease and local.

Q_ATTRIB_LEASE_ONLY

Lease only; no local.

Q_ATTRIB_RMT_BATCH_LOCAL
Q_ATTRIB_RMT_BATCH_ONLY

Remote batch only.

Q_ATTRIB_RESOURCE_RESERVE

Memory reservation.

Q_ATTRIB_FS_DISPATCH_ORDER_QUEUE

Cross-queue fairshare.

Q_ATTRIB_BATCH

Batch queue/partition.

Q_ATTRIB_ONLINE

Online partition.

Q_ATTRIB_INTERRUPTIBLE_BACKFILL

Interruptible backfill.

Q_ATTRIB_APS

This queue sets an absolute priority scheduling (APS) value.

qStatus

The status of the queue. It is the bitwise inclusive OR of some of the following values:

QUEUE_STAT_OPEN

The queue is open to accept newly submitted jobs.

QUEUE_STAT_ACTIVE

The queue is actively dispatching jobs. The queue can be inactivated and reactivated by the LSF administrator using lsb_queuecontrol(). The queue will also be inactivated when its run or dispatch window is closed. In this case it cannot be reactivated manually; it will be reactivated by the LSF system when its run and dispatch windows reopen.

QUEUE_STAT_RUN

The queue run and dispatch windows are open.

The initial state of a queue at LSF boot time is open and either active or inactive, depending on its run and dispatch windows.

QUEUE_STAT_NOPERM

Remote queue rejecting jobs.

QUEUE_STAT_DISC

Remote queue status is disconnected.

QUEUE_STAT_RUNWIN_CLOSE

Queue run windows are closed.

maxJobs

The maximum number of jobs dispatched by the queue and not yet finished.

numJobs

Number of jobs in the queue, including pending, running, and suspended jobs.

numPEND

Number of pending jobs in the queue.

numRUN

Number of running jobs in the queue.

numSSUSP

Number of system suspended jobs in the queue.

numUSUSP

Number of user suspended jobs in the queue.

mig

The queue migration threshold in minutes.

schedDelay

The number of seconds that a new job waits, before being scheduled. A value of zero (0) means the job is scheduled without any delay.

acceptIntvl

The number of seconds for a host to wait after dispatching a job to a host, before accepting a second job to dispatch to the same host.

windowsD

A blank-separated list of time windows describing the dispatch window of the queue. When a queue's dispatch window is closed, no job from this queue will be dispatched. The default is no restriction, or always open (i.e., 24 hours a day, seven days a week).

For the time window format, see window above.

nqsQueues

A blank-separated list of queue specifiers. Each queue specifier is of the form queue@host where host is an NQS host name and queue is the name of a queue on that host.

userShares

A blank-separated list of user shares. Each share is of the form [user, share] where user is a user name, a user group name, the reserved word default or the reserved word others, and share is the number of shares the user gets.

defaultHostSpec

The value of DEFAULT_HOST_SPEC in the Queue section for this queue in the lsb.queues file.

procLimit

An LSF resource limit used to limit the number of job slots (processors) a (parallel) job in the queue will use. A job submitted to this queue must specify a number of processors not greater than this limit.

admins

A list of administrators of the queue. The users whose names are here are allowed to operate on the jobs in the queue and on the queue itself.

preCmd

Queue's pre-exec command. The command is executed before the real batch job is run on the execution host (or on the first host selected for a parallel batch job).

postCmd

Queue's post-exec command. The command is run when a job terminates.

requeueEValues

Jobs that exit with these values are automatically requeued.

hostJobLimit

The maximum number of job slots a host can process from this queue, including job slots of dispatched jobs which have not finished yet and reserved slots for some PEND jobs. This limit controls the number of jobs sent to each host, regardless of a uniprocessor host or multiprocessor host. Default value for this limit is infinity.

resReq

Resource requirement string used to determine eligible hosts for a job.

numRESERVE

Number of reserved job slots for pending jobs.

slotHoldTime

The time used to hold the reserved job slots for a PEND job in this queue.

sndJobsTo

Remote MultiCluster send-jobs queues to forward jobs to.

rcvJobsFrom

Remote MultiCluster receive-jobs queues that can forward to this queue.

resumeCond

Resume threshold conditions for a suspended job in this queue.

stopCond

Stop threshold conditions for a running job in this queue.

jobStarter

Job starter command for a running job in this queue.

suspendActCmd

Command configured for the SUSPEND action.

resumeActCmd

Command configured for the RESUME action.

terminateActCmd

Command configured for the TERMINATE action.

preemption

Preemptive scheduling and preemption policy specified for the queue.

maxRschedTime

Time period for a remote cluster to schedule a job.

MultiCluster job forwarding model only. Determines how long a MultiCluster job stays pending in the execution cluster before returning to the submission cluster. The remote timeout limit in seconds is:

MAX_RSCHED_TIME * MBD_SLEEP_TIME=timeout 
numOfSAccts, shareAccts

(Only used for queues with fairshare policy) a share account vector capturing the fairshare information of the users using the queue.

The storage for the array of queueInfoEnt structures will be reused by the next call.

chkpntDir

The directory where the checkpoint files are created.

chkpntPeriod

The checkpoint period in minutes.

imptJobBklg

MultiCluster job forwarding model only. Specifies the MultiCluster pending job limit for a receive-jobs queue. This represents the maximum number of MultiCluster import jobs that can be pending in the queue; once the limit has been reached, the queue stops accepting jobs from remote clusters.

defLimits[LSF_RLIM_NLIMITS]

The default (soft) resource limits for all jobs submitted to this queue (see getrlimit() and lsb.queues).

chunkJobSize

The maximum number of jobs allowed to be dispatched together in one job chunk. Must be a positive integer greater than 1.

minProcLimit

The minimum number of job slots (processors) that a job in the queue will use.

defProcLimit

The default (soft) limit on the number of job slots (processors) that a job in the queue will use.

fairshareQueues

The list of queues for cross-queue fairshare.

defExtSched

Default external scheduling options for the queue.

mandExtSched

Mandatory external scheduling options for the queue.

slotShare

Share of job slots for queue-based fairshare. Represents the percentage of running jobs (job slots) in use from the queue. SLOT_SHARE must be greater than zero (0) and less than or equal to 100.

The sum of SLOT_SHARE for all queues in the pool does not need to be 100%. It can be more or less, depending on your needs.

slotPool

Name of the pool of job slots the queue belongs to for queue-based fairshare. A queue can only belong to one pool. All queues in the pool must share the same set of hosts.

Specify any ASCII string up to 60 characters long. You can use letters, digits, underscores (_) or dashes (-). You cannot use blank spaces.

underRCond

Specifies a threshold for job underrun exception handling. If a job exits before the specified number of minutes, LSF invokes LSF_SERVERDIR/eadmin to trigger the action for a job underrun exception.

overRCond

Specifies a threshold for job overrun exception handling. If a job runs longer than the specified run time, LSF invokes LSF_SERVERDIR/eadmin to trigger the action for a job overrun exception.

idleCond

Specifies a threshold for idle job exception handling. The value should be a number between 0.0 and 1.0 representing CPU time/runtime. If the job idle factor is less than the specified threshold, LSF invokes LSF_SERVERDIR/eadmin to trigger the action for a job idle exception.

underRJobs

The number of underrun jobs in the queue.

overRJobs

The number of overrun jobs in the queue.

idleJobs

The number of idle jobs in the queue.

warningTimePeriod

Specifies the amount of time before a job control action occurs that a job warning action is to be taken. For example, 2 minutes before the job reaches run time limit or termination deadline, or the queue's run window is closed, an URG signal is sent to the job.

Job action warning time is not normalized.

A job action warning time must be specified with a job warning action in order for job warning to take effect.

warningAction

Specifies the job action to be taken before a job control action occurs. For example, 2 minutes before the job reaches run time limit or termination deadline, or the queue's run window is closed, an URG signal is sent to the job.

A job warning action must be specified with a job action warning time in order for job warning to take effect.

If specified, LSF sends the warning action to the job before the actual control action is taken. This allows the job time to save its result before being terminated by the job control action.

You can specify actions similar to the JOB_CONTROLS queue level parameter: send a signal, invoke a command, or checkpoint the job.

AcResReq

symJobLimit

Limit of running session scheduler jobs.

cpuReq

cpu_req for service partition of session scheduler.

proAttr

Indicate whether it would be willing to donate/borrow.

lendLimit

The maximum number of hosts to lend.

hostReallocInterval

The grace period to lend/return idle hosts.

numCPURequired

Number of CPUs required by CPU provision.

numCPUAllocated

Number of CPUs actually allocated.

numCPUBorrowed

Number of CPUs borrowed.

numCPULent

Number of CPUs lent.

schGranularity

The scheduling granularity. in milliseconds.

symTaskGracePeriod

The grace period for stopping session scheduler tasks.

minOfSsm

The minimum number of SSMs.

maxOfSsm

The maximum number of SSMs.

numOfAllocSlots

The number of allocated slots.

servicePreemption

The service preemption policy.

provisionStatus

Dynamic CPU provision status.

minTimeSlice

The minimum time for preemption and backfill, in seconds.

queueGroup

List of queues defined in a queue group for absolute priority scheduling (APS) across multiple queues.

numApsFactors

The number of calculation factors for absolute priority scheduling (APS).

apsFactorInfo

List of calculation factors for absolute priority scheduling (APS).

apsFactorMap

The mapping of factors to subfactors for absolute priority scheduling (APS).

apsLongNameMap

The mapping of factors to their long names for absolute priority scheduling (APS).

maxJobPreempt

Maximum number of job preempted times.

maxPreExecRetry

Maximum number of pre-exec retry times.

localMaxPreExecRetry

Maximum number of pre-exec retry times for local cluster.

maxJobRequeue

Maximum number of job re-queue times.

usePam

Use Linux-PAM.

cu_type_exclusive

Compute unit type.

cu_str_exclusive

A string specified in EXCLUSIVE+CU[<string>].

shareAcctInfoEnt structure fields

The shareAcctInfoEnt structure contains the following fields:

shareAcctPath

The user name or user group name. (See lsb_userinfo() and lsb_usergrpinfo().)

shares

The number of shares assigned to the user or user group, as configured in the file lsb.queues.

numStartJobs

The number of job slots (belonging to the user or user group) that are running or suspended in the fairshare queue.

histCpuTime

The normalized CPU time accumulated in the fairshare queue by jobs belonging to the user or user group, over the time period configured in the file lsb.params. The default time period is 5 hours.

priority

The priority of the user or user group in the fairshare queue. Larger values represent higher priorities. Job belonging to the user or user group with the highest priority are considered first for dispatch in the fairshare queue. In general, a user or user group with more shares, fewer numStartJobs and less histCpuTime has higher priority.

numReserveJobs

The number of job slots that are reserved for the PEND jobs belonging to the user or user group in the host partition.

runTime

The time unfinished jobs spend in the RUN state.

shareAdjustment

The fairshare adjustment value from the fairshare plugin (libfairshareadjust.*). The adjustment is enabled and weighted by setting the value of FAIRSHARE_ADJUSTMENT_FACTOR in lsb.params.

RETURN VALUES

array: queueInfoEnt

An array of queueInfoEnt structures which store the queue information and sets *numQueues to the size of the array.

char:NULL

Function failed.

ERRORS

If the function fails, lsberrno is set to indicate the error. If lsberrno is LSBE_BAD_QUEUE, (*queues)[*numQueues] is not a queue known to the LSF system. Otherwise, if *numQueues is less than its original value, *numQueues is the actual number of queues found.

SEE ALSO

Related APIs

lsb_hostinfo() - Get information about job server hosts

lsb_userinfo() - Get information about users

lsb_usergrpinfo() - Get information about user groups

Equivalent command

bqueues

Files

$LSB_CONFDIR/cluster_name/lsb.queues


Platform Computing Inc.
www.platform.com
Knowledge Center         Contents    Previous  Next