Knowledge Center Contents Previous Next |
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.
- LSF_RLIMIT_CPU CPULIMIT
- LSF_RLIMIT_FSIZE FILELIMIT
- LSF_RLIMIT_DATA DATALIMIT
- LSF_RLIMIT_STACK STACKLIMIT
- LSF_RLIMIT_CORE CORELIMIT
- LSF_RLIMIT_RSS MEMLIMIT
- LSF_RLIMIT_RUN RUNLIMIT
- LSF_RLIMIT_PROCESS PROCESSLIMIT
- LSF_RLIMIT_SWAP SWAPLIMIT
- LSF_RLIMIT_THREAD
- LSF_RLIMIT_NOFILE
- LSF_RLIMIT_OPENMAX
- LSF_RLIMIT_VMEM
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=timeoutnumOfSAccts, 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 |