Slurm(3pm)

1Slurm(3)              User Contributed Perl Documentation             Slurm(3)
2
3
4

NAME

6       Slurm - Perl API for libslurm
7

SYNOPSIS

9           use Slurm;
10
11           my $slurm = Slurm::new();
12           $nodes = $slurm->load_node();
13           unless($nodes) {
14               die "failed to load node info: " . $slurm->strerror();
15           }
16

DESCRIPTION

18       The Slurm class provides Perl interface of the Slurm API functions in
19       "<slurm/slurm.h>", with some extra frequently used functions exported
20       by libslurm.
21
22   METHODS
23       To use the API, first create a Slurm object:
24
25           $slurm = Slurm::new($conf);
26
27       Then call the desired functions:
28
29           $resp = $slurm->load_jobs();
30
31       In the following "METHODS" section, if a parameter is omitted, it will
32       be listed as "param=val" , where "val" is the default value of the
33       parameter.
34
35   DATA STRUCTURES
36       Typically, C structures are converted to (maybe blessed) Perl hash
37       references, with field names as hash keys. Arrays in C are converted to
38       arrays in Perl. For example, there is a structure "job_info_msg_t":
39
40           typedef struct job_info_msg {
41               time_t last_update;     /* time of latest info */
42               uint32_t record_count;  /* number of records */
43               job_info_t *job_array;  /* the job records */
44           } job_info_msg_t;
45
46       This will be converted to a hash reference with the following
47       structure:
48
49           {
50               last_update => 1285847672,
51               job_array => [ {account => 'test', alloc_node => 'ln0', alloc_sid => 1234, ...},
52                              {account => 'debug', alloc_node => 'ln2', alloc_sid => 5678, ...},
53                              ...
54                            ]
55           }
56
57       Note the missing of the "record_count" field in the hash. It can be
58       derived from the number of elements in array "job_array".
59
60       To pass parameters to the API functions, use the corresponding hash
61       references, for example:
62
63           $rc = $slurm->update_node({node_names => 'node[0-7]', node_state => NODE_STATE_DRAIN});
64
65       Please see "<slurm/slurm.h>" for the definition of the structures.
66
67   CONSTANTS
68       The enumerations and macro definitions are available in the Slurm
69       package. If ':constant' is given when using the Slurm package, the
70       constants will be exported to the calling package.
71
72       Please see Slurm::Constant for the available constants.
73

METHODS

75   CONSTRUCTOR/DESTRUCTOR
76       $slurm = Slurm::new($conf_file=undef);
77
78       Create a Slurm object. For now the object is just a hash reference with
79       no members.
80
81       · IN $conf_file: the Slurm configuration file. If omitted, the default
82         Slurm configuration file will be used (file specified by environment
83         variable SLURM_CONF or the file slurm.conf under directroy specified
84         in compile time).
85
86       · RET: blessed opaque Slurm object. On error "undef" is returned.
87
88   ERROR INFORMATION FUNCTIONS
89       $errno = $slurm->get_errno();
90
91       Get the error number associated with last operation.
92
93       · RET: error number associated with last operation.
94
95       $str = $slurm->strerror($errno=0)
96
97       Get the string describing the specified error number.
98
99       · IN $errno: error number. If omitted or 0, the error number returned
100         by "$slurm-"get_errno()> will be used.
101
102       · RET: error string.
103
104   ENTITY STATE/REASON/FLAG/TYPE STRING FUNCTIONS
105       $str = $slurm->preempt_mode_string($mode_num);
106
107       Get the string describing the specified preemt mode number.
108
109       · IN $mode_num: preempt mode number.
110
111       · RET: preempt mode string.
112
113       $num = $slurm->preempt_mode_num($mode_str);
114
115       Get the preempt mode number of the specified preempt mode string.
116
117       · IN $mode_str: preempt mode string.
118
119       · RET: preempt mode number.
120
121       $str = $slurm->job_reason_string($num);
122
123       Get the string representation of the specified job state reason number.
124
125       · IN $num: job reason number.
126
127       · RET: job reason string.
128
129       $str = $slurm->job_state_string($num);
130
131       Get the string representation of the specified job state number.
132
133       · IN $num: job state number.
134
135       · RET: job state string.
136
137       $str = $slurm->job_state_string_compact($num);
138
139       Get the compact string representation of the specified job state
140       number.
141
142       · IN $num: job state number.
143
144       · RET: compact job state string.
145
146       $num = $slurm->job_state_num($str);
147
148       Get the job state number of the specified (compact) job state string.
149
150       · IN $str: job state string.
151
152       · RET: job state number.
153
154       $str = $slurm->reservation_flags_string($flags);
155
156       Get the string representation of the specified reservation flags.
157
158       · IN $num: reservation flags number.
159
160       · RET: reservation flags string.
161
162       $str = $slurm->node_state_string($num);
163
164       Get the string representation of the specified node state number.
165
166       · IN $num: node state number.
167
168       · RET: node state string.
169
170       $str = $slurm->node_state_string_compact($num);
171
172       Get the compact string representation of the specified node state
173       number.
174
175       · IN $num: node state number.
176
177       · RET: compact node state string.
178
179       $str = $slurm->private_data_string($num);
180
181       Get the string representation of the specified private data type.
182
183       · IN $num: private data type number.
184
185       · RET: private data type string.
186
187       $str = $slurm->accounting_enforce_string($num);
188
189       Get the string representation of the specified accounting enforce type.
190
191       · IN $num: accounting enforce type number.
192
193       · RET: accounting enforce type string.
194
195   RESOURCE ALLOCATION FUNCTIONS
196       $resp = $slurm->allocate_resources($job_desc);
197
198       Allocate resources for a job request. If the requested resources are
199       not immediately available, the slurmctld will send the
200       job_alloc_resp_msg to the sepecified node and port.
201
202       · IN $job_desc: description of resource allocation request, with
203         structure of "job_desc_msg_t".
204
205       · RET: response to request, with structure of
206         "resource_allocation_response_msg_t".  This only represents a job
207         allocation if resources are immediately available.  Otherwise it just
208         contains the job id of the enqueued job request. On failure "undef"
209         is returned.
210
211       $resp = $slurm->allocate_resources_blocking($job_desc, $timeout=0,
212       $pending_callbacks=undef);
213
214       Allocate resources for a job request.  This call will block until the
215       allocation is granted, or the specified timeout limit is reached.
216
217       · IN $job_desc: description of resource allocation request, with
218         structure of "job_desc_msg_t".
219
220       · IN $timeout: amount of time, in seconds, to wait for a response
221         before giving up. A timeout of zero will wait indefinitely.
222
223       · IN $pending_callbacks: If the allocation cannot be granted
224         immediately, the controller will put the job in the PENDING state.
225         If pending callback is given, it will be called with the job id of
226         the pending job as the sole parameter.
227
228       · RET: allcation response, with structure of
229         "resource_allocation_response_msg_t". On failure "undef" is returned,
230         with errno set.
231
232       $resp = $slurm->allocatiion_lookup($job_id);
233
234       Retrieve info for an existing resource allocation.
235
236       · IN $job_id: job allocation identifier.
237
238       · RET: job allocation info, with structure of
239         "resource_allocation_response_msg_t". On failure "undef" is returned
240         with errno set.
241
242       $str = $slurm->read_hostfile($filename, $n);
243
244       Read a specified Slurm hostfile. The file must contain a list of Slurm
245       NodeNames, one per line.
246
247       · IN $filename: name of Slurm hostlist file to be read.
248
249       · IN $n: number of NodeNames required.
250
251       · RET: a string representing the hostlist. Returns NULL if there are
252         fewer than $n hostnames in the file, or if an error occurs.
253
254       $msg_thr = $slurm->allocation_msg_thr_create($port, $callbacks);
255
256       Startup a message handler talking with the controller dealing with
257       messages from the controller during an allocation.
258
259       · OUT $port: port we are listening for messages on from the controller.
260
261       · IN $callbacks: callbacks for different types of messages, with
262         structure of "slurm_allocation_callbacks_t".
263
264       · RET: opaque object of "allocation_msg_thread_t *",  or NULL on
265         failure.
266
267       $slurm->allocation_msg_thr_destroy($msg_thr);
268
269       Shutdown the message handler talking with the controller dealing with
270       messages from the controller during an allocation.
271
272       · IN $msg_thr: opaque object of "allocation_msg_thread_t" pointer.
273
274       $resp = $slurm->submit_batch_job($job_desc_msg);
275
276       Issue RPC to submit a job for later execution.
277
278       · IN $job_desc_msg: description of batch job request, with structure of
279         "job_desc_msg_t".
280
281       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
282         errno set.
283
284       $rc = $slurm->job_will_run($job_desc_msg);
285
286       Determine if a job would execute immediately if submitted now.
287
288       · IN $job_desc_msg: description of resource allocation request, with
289         structure of "job_desc_msg_t".
290
291       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
292         errno set.
293
294       $resp = $slurm->sbcast_lookup($job_id);
295
296       Retrieve info for an existing resource allocation including a
297       credential needed for sbcast.
298
299       · IN $jobid: job allocation identifier.
300
301       · RET: job allocation information includeing a credential for sbcast,
302         with structure of "job_sbcast_cred_msg_t". On failure "undef" is
303         returned with errno set.
304
305   JOB/STEP SIGNALING FUNCTIONS
306       $rc = $slurm->kill_job($job_id, $signal, $batch_flag=0);
307
308       Send the specified signal to all steps of an existing job.
309
310       · IN $job_id: the job's id.
311
312       · IN $signal: signal number.
313
314       · IN $batch_flag: 1 to signal batch shell only, otherwise 0.
315
316       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
317         errno set.
318
319       $rc = $slurm->kill_job_step($job_id, $step_id, $signal);
320
321       Send the specified signal to an existing job step.
322
323       · IN $job_id: the job's id.
324
325       · IN $step_id: the job step's id.
326
327       · IN $signal: signal number.
328
329       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
330         errno set.
331
332       $rc = $slurm->signal_job($job_id, $signal);
333
334       Send the specified signal to all steps of an existing job.
335
336       · IN $job_id: the job's id.
337
338       · IN $signal: signal number.
339
340       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
341         errno set.
342
343       $rc = $slurm->signal_job_step($job_id, $step_id, $signal);
344
345       Send the specified signal to an existing job step.
346
347       · IN $job_id: the job's id.
348
349       · IN $step_id: the job step's id.
350
351       · IN $signal: signal number.
352
353       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
354         errno set.
355
356   JOB/STEP COMPLETION FUNCTIONS
357       $rc = $slurm->complete_job($job_id, $job_rc=0);
358
359       Note the completion of a job and all of its steps.
360
361       · IN $job_id: the job's id.
362
363       · IN $job_rc: the highest exit code of any task of the job.
364
365       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
366         errno set.
367
368       $rc = $slurm->terminate_job_step($job_id, $step_id);
369
370       Terminates a job step by sending a REQUEST_TERMINATE_TASKS rpc to all
371       slurmd of a job step, and then calls slurm_complete_job_step() after
372       verifying that all nodes in the job step no longer have running tasks
373       from the job step.  (May take over 35 seconds to return.)
374
375       · IN $job_id: the job's id.
376
377       · IN $step_id: the job step's id - use SLURM_BATCH_SCRIPT as the
378         step_id to terminate a job's batch script.
379
380       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
381         errno set.
382
383   Slurm TASK SPAWNING FUNCTIONS
384       $ctx = $slurm->step_ctx_create($params);
385
386       Create a job step and its context.
387
388       · IN $params: job step parameters, with structure of
389         "slurm_step_ctx_params_t".
390
391       · RET: the step context. On failure "undef" is returned with errno set.
392
393       $ctx = $slurm->step_ctx_create_no_alloc($params);
394
395       Create a job step and its context without getting an allocation.
396
397       · IN $params: job step parameters, with structure of
398         "slurm_step_ctx_params_t"..
399
400       · IN $step_id: fake job step id.
401
402       · RET: the step context. On failure "undef" is returned with errno set.
403
404   SLURM CONTROL CONFIGURATION READ/PRINT/UPDATE FUNCTIONS
405       ($major, $minor, $micro) = $slurm->api_version();
406
407       Get the Slurm API's version number.
408
409       · RET: a three element list of the major, minor, and micro version
410         number.
411
412       $resp = $slurm->load_ctl_conf($update_time=0);
413
414       Issue RPC to get Slurm control configuration information if changed.
415
416       · IN $update_time: time of current configuration data.
417
418       · RET: Slurm configuration data, with structure of "slurm_ctl_conf_t".
419         On failure "undef" is returned with errno set.
420
421       $slurm->print_ctl_conf($out, $conf);
422
423       Output the contents of Slurm control configuration message as loaded
424       using "load_ctl_conf()".
425
426       · IN $out: file to write to.
427
428       · IN $conf: Slurm control configuration, with structure of
429         "slurm_ctl_conf_t".
430
431       $list = $slurm->ctl_conf_2_key_pairs($conf);
432
433       Put the Slurm configuration data into a List of opaque data type
434       "config_key_pair_t".
435
436       · IN $conf: Slurm control configuration, with structure of
437         "slurm_ctl_conf_t".
438
439       · RET: List of opaque data type "config_key_pair_t".
440
441       $resp = $slurm->load_slurmd_status();
442
443       Issue RPC to get the status of slurmd daemon on this machine.
444
445       · RET: slurmd status info, with structure of "slurmd_status_t". On
446         failure "undef" is returned with errno set.
447
448       $slurm->print_slurmd_status($out, $slurmd_status);
449
450       Output the contents of slurmd status message as loaded using
451       "load_slurmd_status()".
452
453       · IN $out: file to write to.
454
455       · IN $slurmd_status: slurmd status info, with structure of
456         "slurmd_status_t".
457
458       $slurm->print_key_pairs($out, $key_pairs, $title);
459
460       Output the contents of key_pairs which is a list of opaque data type
461       "config_key_pair_t".
462
463       · IN $out: file to write to.
464
465       · IN $key_pairs: List containing key pairs to be printed.
466
467       · IN $title: title of key pair list.
468
469       $rc = $slurm->update_step($step_msg);
470
471       Update the time limit of a job step.
472
473       · IN $step_msg: step update messasge descriptor, with structure of
474         "step_update_request_msg_t".
475
476       · RET: 0 or -1 on error.
477
478   SLURM JOB RESOURCES READ/PRINT FUNCTIONS
479       $num = $slurm->job_cpus_allocated_on_node_id($job_res, $node_id);
480
481       Get the number of cpus allocated to a job on a node by node id.
482
483       · IN $job_res: job resources data, with structure of "job_resources_t".
484
485       · IN $node_id: zero-origin node id in allocation.
486
487       · RET: number of CPUs allocated to job on this node or -1 on error.
488
489       $num = $slurm->job_cpus_allocated_on_node($job_res, $node_name);
490
491       Get the number of cpus allocated to a job on a node by node name.
492
493       · IN $job_res: job resources data, with structure of "job_resources_t".
494
495       · IN $node_name: name of node.
496
497       · RET: number of CPUs allocated to job on this node or -1 on error.
498
499   SLURM JOB CONFIGURATION READ/PRINT/UPDATE FUNCTIONS
500       $time = $slurm->get_end_time($job_id);
501
502       Get the expected end time for a given slurm job.
503
504       · IN $jobid: Slurm job id.
505
506       · RET: scheduled end time for the job. On failure "undef" is returned
507         with errno set.
508
509       $secs = $slurm->get_rem_time($job_id);
510
511       Get the expected time remaining for a given job.
512
513       · IN $jobid: Slurm job id.
514
515       · RET: remaining time in seconds or -1 on error.
516
517       $rc = $slurm->job_node_ready($job_id);
518
519       Report if nodes are ready for job to execute now.
520
521       · IN $job_id: Slurm job id.
522
523       · RET:
524
525         · READY_JOB_FATAL: fatal error
526
527         · READY_JOB_ERROR: ordinary error
528
529         · READY_NODE_STATE: node is ready
530
531         · READY_JOB_STATE: job is ready to execute
532
533       $resp = $slurm->load_job($job_id, $show_flags=0);
534
535       Issue RPC to get job information for one job ID.
536
537       · IN $job_id: ID of job we want information about.
538
539       · IN $show_flags: job filtering options.
540
541       · RET: job information, with structure of "job_info_msg_t". On failure
542         "undef" is returned with errno set.
543
544       $resp = $slurm->load_jobs($update_time=0, $show_flags=0);
545
546       Issue RPC to get all Slurm job information if changed.
547
548       · IN $update_time: time of current job information data.
549
550       · IN $show_flags: job filtering options.
551
552       · RET: job information, with structure of "job_info_msg_t". On failure
553         "undef" is returned with errno set.
554
555       $rc = $slurm->notify_job($job_id, $message);
556
557       Send message to the job's stdout, usable only by user root.
558
559       · IN $job_id: Slurm job id or 0 for all jobs.
560
561       · IN $message: arbitrary message.
562
563       · RET: 0 or -1 on error.
564
565       $job_id = $slurm->pid2jobid($job_pid);
566
567       Issue RPC to get the Slurm job ID of a given process ID on this
568       machine.
569
570       · IN $job_pid: process ID of interest on this machine.
571
572       · RET: corresponding job ID. On failure "undef" is returned.
573
574       $slurm->print_job_info($out, $job_info, $one_liner=0);
575
576       Output information about a specific Slurm job based upon message as
577       loaded using "load_jobs()".
578
579       · IN $out: file to write to.
580
581       · IN $job_info: an individual job information record, with structure of
582         "job_info_t".
583
584       · IN $one_liner: print as a single line if true.
585
586       $slurm->print_job_info_msg($out, $job_info_msg, $one_liner=0);
587
588       Output information about all Slurm jobs based upon message as loaded
589       using "load_jobs()".
590
591       · IN $out: file to write to.
592
593       · IN $job_info_msg: job information message, with structure of
594         "job_info_msg_t".
595
596       · IN $one_liner: print as a single line if true.
597
598       $str = $slurm->sprint_job_info($job_info, $one_liner=0);
599
600       Output information about a specific Slurm job based upon message as
601       loaded using "load_jobs()".
602
603       · IN $job_info: an individual job information record, with structure of
604         "job_info_t".
605
606       · IN $one_liner: print as a single line if true.
607
608       · RET: string containing formatted output.
609
610       $rc = $slurm->update_job($job_info);
611
612       Issue RPC to a job's configuration per request only usable by user root
613       or (for some parameters) the job's owner.
614
615       · IN $job_info: description of job updates, with structure of
616         "job_desc_msg_t".
617
618       · RET: SLURM_SUCCESS on success, otherwise return SLURM_ERROR with
619         errno set.
620
621   SLURM JOB STEP CONFIGURATION READ/PRINT/UPDATE FUNCTIONS
622       $resp = $slurm->get_job_steps($update_time=0, $job_id=NO_VAL,
623       $step_id=NO_VAL, $show_flags=0);
624
625       Issue RPC to get specific slurm job step configuration information if
626       changed since update_time.
627
628       · IN $update_time: time of current configuration data.
629
630       · IN $job_id: get information for specific job id, NO_VAL for all jobs.
631
632       · IN $step_id: get information for specific job step id, NO_VAL for all
633         job steps.
634
635       · IN $show_flags: job step filtering options.
636
637       · RET: job step information, with structure of
638         "job_step_info_response_msg_t". On failure "undef" is returned with
639         errno set.
640
641       $slurm->print_job_step_info_msg($out, $step_info_msg, $one_liner);
642
643       Output information about all Slurm job steps based upon message as
644       loaded using "get_job_steps()".
645
646       · IN $out: file to write to.
647
648       · IN $step_info_msg: job step information message, with structure of
649         "job_step_info_response_msg_t".
650
651       · IN $one_liner: print as a single line if true.
652
653       $slurm->print_job_step_info($out, $step_info, $one_liner);
654
655       Output information about a specific Slurm job step based upon message
656       as loaded using "get_job_steps()".
657
658       · IN $out: file to write to.
659
660       · IN $step_info: job step information, with structure of
661         "job_step_info_t".
662
663       · IN $one_liner: print as a single line if true.
664
665       $str = $slurm->sprint_job_step_info($step_info, $one_liner);
666
667       Output information about a specific Slurm job step based upon message
668       as loaded using "get_job_steps()".
669
670       · IN $step_info: job step information, with structure of
671         "job_step_info_t".
672
673       · IN $one_liner: print as a single line if true.
674
675       · RET: string containing formatted output.
676
677       $layout = $slurm->job_step_layout_get($job_id, $step_id);
678
679       Get the layout structure for a particular job step.
680
681       · IN $job_id: Slurm job ID.
682
683       · IN $step_id: Slurm step ID.
684
685       · RET: layout of the job step, with structure of "slurm_step_layout_t".
686         On failure "undef" is returned with errno set.
687
688       $resp = $slurm->job_step_stat($job_id, $step_id, $nodelist=undef);
689
690       Get status of a current step.
691
692       · IN $job_id : Slurm job ID.
693
694       · IN $step_id: Slurm step ID.
695
696       · IN $nodelist: nodes to check status of step. If omitted, all nodes in
697         step are used.
698
699       · RET: response of step status, with structure of
700         "job_step_stat_response_msg_t". On failure "undef" is returned.
701
702       $resp = $slurm->job_step_get_pids($job_id, $step_id, $nodelist);
703
704       Get the complete list of pids for a given job step.
705
706       · IN $job_id: Slurm job ID.
707
708       · IN $step_id: Slurm step ID.
709
710       · IN $nodelist: nodes to check pids of step. If omitted, all nodes in
711         step are used.
712
713       · RET: response of pids information, with structure of
714         "job_step_pids_response_msg_t". On failure "undef" is returned.
715
716   SLURM NODE CONFIGURATION READ/PRINT/UPDATE FUNCTIONS
717       $resp = $slurm->load_node($update_time=0, $show_flags=0);
718
719       Issue RPC to get all node configuration information if changed.
720
721       · IN $update_time: time of current configuration data.
722
723       · IN $show_flags: node filtering options.
724
725       · RET: response hash reference with structure of "node_info_msg_t". On
726         failure "undef" is returned with errno set.
727
728       $slurm->print_node_info_msg($out, $node_info_msg, $one_liner=0);
729
730       Output information about all Slurm nodes based upon message as loaded
731       using "load_node()".
732
733       · IN $out: FILE handle to write to.
734
735       · IN $node_info_msg: node information message to print, with structure
736         of "node_info_msg_t".
737
738       · IN $one_liner: if true, each node info will be printed as a single
739         line.
740
741       $slurm->print_node_table($out, $node_info, $one_liner=0);
742
743       Output information about a specific Slurm node based upon message as
744       loaded using "load_node()".
745
746       · IN $out: FILE handle to write to.
747
748       · IN $node_info: an individual node information record with structure
749         of "node_info_t".
750
751       · IN $one_liner: whether to print as a single line.
752
753       $str = $slurm->sprint_node_table($node_info, $one_liner=0);
754
755       Output information about a specific Slurm node based upon message as
756       loaded using "load_node".
757
758       · IN $node_info: an individual node information record with structure
759         of "node_info_t".
760
761       · IN $one_liner: whether to print as a single line.
762
763       · RET: string containing formatted output on success, "undef" on
764         failure.
765
766       $rc = $slurm->update_node($node_info);
767
768       Issue RPC to modify a node's configuration per request, only usable by
769       user root.
770
771       · IN $node_info: description of node updates, with structure of
772         "update_node_msg_t".
773
774       · RET: 0 on success, -1 on failure with errno set.
775
776   SLURM SWITCH TOPOLOGY CONFIGURATION READ/PRINT FUNCTIONS
777       $resp = $slurm->load_topo();
778
779       Issue RPC to get all switch topology configuration information.
780
781       · RET: response hash reference with structure of
782         "topo_info_response_msg_t". On failure "undef" is returned with errno
783         set.
784
785       $slurm->print_topo_info_msg($out, $topo_info_msg, $one_liner=0);
786
787       Output information about all switch topology configuration information
788       based upon message as loaded using "load_topo()".
789
790       · IN $out: FILE handle to write to.
791
792       · IN $topo_info_msg: swith topology information message, with structure
793         of "topo_info_response_msg_t".
794
795       · IN $one_liner: print as a single line if not zero.
796
797       $slurm->print_topo_record($out, $topo_info, $one_liner);
798
799       Output information about a specific Slurm topology record based upon
800       message as loaded using "load_topo()".
801
802       · IN $out: FILE handle to write to.
803
804       · IN $topo_info: an individual switch information record, with
805         structure of "topo_info_t".
806
807       · IN $one_liner: print as a single line if not zero.
808
809   SLURM SELECT READ/PRINT/UPDATE FUNCTIONS
810       $rc = $slurm->get_select_nodeinfo($nodeinfo, $data_type, $state,
811       $data);
812
813       Get data from a select node credential.
814
815       · IN $nodeinfo: select node credential to get data from.
816
817       · IN $data_type: type of data to get.
818
819         · TODO: enumerate data type and returned value.
820
821       · IN $state: state of node query.
822
823       · OUT $data: the data got.
824
825   SLURM PARTITION CONFIGURATION READ/PRINT/UPDATE FUNCTIONS
826       $resp = $slurm->load_partitions($update_time=0, $show_flags=0);
827
828       Issue RPC to get all Slurm partition configuration information if
829       changed.
830
831       · IN $update_time: time of current configuration data.
832
833       · IN $show_flags: partitions filtering options.
834
835       · RET: response hash reference with structure of
836         "partition_info_msg_t".
837
838       $slurm->print_partition_info_msg($out, $part_info_msg, $one_liner=0);
839
840       Output information about all Slurm partitions based upon message as
841       loaded using "load_partitions()".
842
843       · IN $out: FILE handle to write to.
844
845       · IN $part_info_msg: partitions information message, with structure of
846         "partition_info_msg_t".
847
848       · IN $one_liner: print as a single line if true.
849
850       $slurm->print_partition_info($out, $part_info, $one_liner=0);
851
852       Output information about a specific Slurm partition based upon message
853       as loaded using "load_partitions()".
854
855       · IN $out: FILE handle to write to.
856
857       · IN $part_info: an individual partition information record, with
858         structure of "partition_info_t".
859
860       · IN $one_liner: print as a single ine if true.
861
862       $str = $slurm->sprint_partition_info($part_info, $one_liner=0);
863
864       Output information about a specific Slurm partition based upon message
865       as loaded using "load_reservations()".
866
867       · IN $part_info: an individual partition information record, with
868         structure of "partition_info_t".
869
870       · IN $one_liner: print as a single line if true.
871
872       · RET: string containing formatted output. On failure "undef" is
873         returned.
874
875       $rc = $slurm->create_partition($part_info);
876
877       Create a new partition, only usable by user root.
878
879       · IN $part_info: description of partition configuration with structure
880         of "update_part_msg_t".
881
882       · RET: 0 on success, -1 on failure with errno set.
883
884       $rc = $slurm->update_partition($part_info);
885
886       Issue RPC to update a partition's configuration per request, only
887       usable by user root.
888
889       · IN $part_info: description of partition updates with structure of
890         "update_part_msg_t".
891
892       · RET: 0 on success, -1 on failure with errno set.
893
894       $rc = $slurm->delete_partition($part_info)
895
896       Issue RPC to delete a partition, only usable by user root.
897
898       · IN $part_info: description of partition to delete, with structure of
899         "delete_part_msg_t".
900
901       · RET: 0 on success, -1 on failure with errno set.
902
903   SLURM RESERVATION CONFIGURATION READ/PRINT/UPDATE FUNCTIONS
904       $name = $slurm->create_reservation($resv_info);
905
906       Create a new reservation, only usable by user root.
907
908       · IN $resv_info: description of reservation, with structure of
909         "resv_desc_msg_t".
910
911       · RET: name of reservation created. On failure "undef" is returned with
912         errno set.
913
914       $rc = $slurm->update_reservation($resv_info);
915
916       Modify an existing reservation, only usable by user root.
917
918       · IN $resv_info: description of reservation, with structure of
919         "resv_desc_msg_t".
920
921       · RET: error code.
922
923       $rc = $slurm->delete_reservation($resv_info);
924
925       Issue RPC to delete a reservation, only usable by user root.
926
927       · IN $resv_info: description of reservation to delete, with structure
928         of "reservation_name_msg_t".
929
930       · RET: error code
931
932       $resp = $slurm->load_reservations($update_time=0);
933
934       Issue RPC to get all Slurm reservation configuration information if
935       changed.
936
937       · IN $update_time: time of current configuration data.
938
939       · RET: response of reservation information, with structure of
940         "reserve_info_msg_t". On failure "undef" is returned with errno set.
941
942       $slurm->print_reservation_info_msg($out, $resv_info_msg, $one_liner=0);
943
944       Output information about all Slurm reservations based upon message as
945       loaded using "load_reservation()".
946
947       · IN $out: FILE handle to write to.
948
949       · IN $resv_info_msg: reservation information message, with structure of
950         "reserve_info_msg_t".
951
952       · IN $one_liner: print as a single line if true.
953
954       $slurm->print_reservation_info($out, $resv_info, $one_liner=0);
955
956       Output information about a specific Slurm reservation based upon
957       message as loaded using "load_reservation()".
958
959       · IN $out: FILE handle to write to.
960
961       · IN $resv_info: an individual reservation information record, with
962         structure of "reserve_info_t".
963
964       · IN $one_liner: print as a single line if true.
965
966       $str = $slurm->sprint_reservation_info($resv_info, $one_liner=0);
967
968       Output information about a specific Slurm reservation based upon
969       message as loaded using "load_reservations()".
970
971       · IN $resv_info: an individual reservation information record, with
972         structure of "reserve_info_t".
973
974       · IN $one_liner: print as a single line if true.
975
976       · RET: string containing formatted output. On failure "undef" is
977         returned.
978
979   SLURM PING/RECONFIGURE/SHUTDOWN FUNCTIONS
980       $rc = $slurm->ping($primary);
981
982       Issue RPC to ping Slurm controller (slurmctld).
983
984       · IN primary: 1 for primary controller, 2 for secondary controller.
985
986       · RET: error code.
987
988       $rc = $slurm->reconfigure()
989
990       Issue RPC to have Slurm controller (slurmctld) reload its configuration
991       file.
992
993       · RET: error code.
994
995       $rc = $slurm->shutdown($options);
996
997       Issue RPC to have Slurm controller (slurmctld) cease operations, both
998       the primary and backup controller are shutdown.
999
1000       · IN $options:
1001
1002         ·   0: all slurm daemons are shutdown.
1003
1004         ·   1: slurmctld generates a core file.
1005
1006         ·   2: only the slurmctld is shutdown (no core file).
1007
1008       · RET: error code.
1009
1010       $rc = $slurm->takeover();
1011
1012       Issue RPC to have Slurm backup controller take over the primary
1013       controller. REQUEST_CONTROL is sent by the backup to the primary
1014       controller to take control.
1015
1016       · RET: error code.
1017
1018       $rc = $slurm->set_debug_level($debug_level)
1019
1020       Issue RPC to set slurm controller debug level.
1021
1022       · IN $debug_level: requested debug level.
1023
1024       · RET: 0 on success, -1 on error with errno set.
1025
1026       $rc = $slurm->set_schedlog_level($schedlog_level);
1027
1028       Issue RPC to set slurm scheduler log level.
1029
1030       · schedlog_level: requested scheduler log level.
1031
1032       · RET: 0 on success, -1 on error with errno set.
1033
1034   SLURM JOB SUSPEND FUNCTIONS
1035       $rc = $slurm->suspend($job_id);
1036
1037       Suspend execution of a job.
1038
1039       · IN $job_id: job on which top perform operation.
1040
1041       · RET: error code.
1042
1043       $rc = $slurm->resume($job_id);
1044
1045       Resume execution of a previously suspended job.
1046
1047       · IN $job_id: job on which to perform operation.
1048
1049       · RET: error code.
1050
1051       $rc = $slurm->requeue($job_id);
1052
1053       Re-queue a batch job, if already running then terminate it first.
1054
1055       · IN $job_id: job on which to perform operation.
1056
1057       · RET: error code.
1058
1059   SLURM JOB CHECKPOINT FUNCTIONS
1060       $rc = $slurm->checkpoint_able($job_id, $step_id, $start_time);
1061
1062       Determine if the specified job step can presently be checkpointed.
1063
1064       · IN $job_id: job on which to perform operation.
1065
1066       · IN $step_id: job step on which to perform operation.
1067
1068       · OUT $start_time: time at which checkpoint request was issued.
1069
1070       · RET: 0 (can be checkpoined) or a slurm error code.
1071
1072       $rc = $slurm->checkpoint_disable($job_id, $step_id);
1073
1074       Disable checkpoint requests for some job step.
1075
1076       · IN $job_id: job on which to perform operation.
1077
1078       · IN $step_id: job step on which to perform operation.
1079
1080       · RET: error code.
1081
1082       $rc = $slurm->checkpoint_enable($job_id, $step_id);
1083
1084       Enable checkpoint requests for some job step.
1085
1086       · IN $job_id: job on which to perform operation.
1087
1088       · IN $step_id: job step on which to perform operation.
1089
1090       · RET: error code.
1091
1092       $rc = $slurm->checkpoint_create($job_id, $step_id, $max_wait,
1093       $image_dir);
1094
1095       Initiate a checkpoint requests for some job step. The job will continue
1096       execution after the checkpoint operation completes.
1097
1098       · IN $job_id: job on which to perform operation.
1099
1100       · IN $step_id: job step on which to perform operation.
1101
1102       · IN $max_wait: maximum wait for operation to complete, in seconds.
1103
1104       · IN $image_dir: directory to store image files.
1105
1106       · RET: error code.
1107
1108       $rc = $slurm->checkpoint_vacate($job_id, $step_id, $max_wait,
1109       $image_dir);
1110
1111       Initiate a checkpoint requests for some job step. The job will
1112       terminate after the checkpoint operation completes.
1113
1114       · IN $job_id: job on which to perform operation.
1115
1116       · IN $step_id: job step on which to perform operation.
1117
1118       · IN $max_wait: maximum wait for operation to complete, in seconds.
1119
1120       · IN $image_dir: directory to store image files.
1121
1122       · RET: error code.
1123
1124       $rc = $slurm->checkpoint_restart($job_id, $step_id, $stick, $image_dir)
1125
1126       Restart execution of a checkpointed job step.
1127
1128       · IN $job_id: job on which to perform operation.
1129
1130       · IN $step_id: job step on which to perform operation.
1131
1132       · IN $stick: if true, stick to nodes previously running on.
1133
1134       · IN $image_dir: directory to find checkpoint image files.
1135
1136       · RET: error code.
1137
1138       $rc = $slurm->checkpoint_complete($job_id, $step_id, $begin_time,
1139       $error_code, $error_msg);
1140
1141       Note the completion of a job step's checkpoint operation.
1142
1143       · IN $job_id: job on which to perform operation.
1144
1145       · IN $step_id: job step on which to perform operation.
1146
1147       · IN $begin_time: time at which checkpoint began.
1148
1149       · IN $error_code: error code, highest value for all complete calls is
1150         preserved.
1151
1152       · IN $error_msg: error message, preserved for highest error_code.
1153
1154       · RET: error code.
1155
1156       checkpoint_task_complete($job_id, $step_id, $task_id, $begin_time,
1157       $error_code, $error_msg);
1158
1159       Note the completion of a task's checkpoint operation.
1160
1161       · IN $job_id: job on which to perform operation.
1162
1163       · IN $step_id: job step on which to perform operation.
1164
1165       · IN $task_id: task which completed the operation.
1166
1167       · IN $begin_time: time at which checkpoint began.
1168
1169       · IN $error_code: error code, highest value for all complete calls is
1170         preserved.
1171
1172       · IN $error_msg: error message, preserved for highest error_code.
1173
1174       · RET: error code.
1175
1176       $rc = $slurm->checkpoint_error($job_id, $step_id, $error_code,
1177       $error_msg);
1178
1179       Gather error information for the last checkpoint operation for some job
1180       step.
1181
1182       · IN $job_id: job on which to perform operation.
1183
1184       · IN $step_id: job step on which to perform operation.
1185
1186       · OUT $error_code: error number associated with the last checkpoint
1187         operation.
1188
1189       · OUT $error_msg: error message associated with the last checkpoint
1190         operation.
1191
1192       · RET: error code.
1193
1194       $rc = $slurm->checkpoint_tasks($job_id, $step_id, $image_dir,
1195       $max_wait, $nodelist);
1196
1197       Send checkoint request to tasks of specified job step.
1198
1199       · IN $job_id: job on which to perform operation.
1200
1201       · IN $step_id: job step on which to perform operation.
1202
1203       · IN $image_dir: location to store checkpoint image files.
1204
1205       · IN $max_wait: seconds to wait for the operation to complete.
1206
1207       · IN $nodelist: nodes to send the request.
1208
1209       · RET: 0 on success, non-zero on failure with errno set.
1210
1211   SLURM TRIGGER FUNCTIONS
1212       $rc = $slurm->set_trigger($trigger_info);
1213
1214       Set an event trigger.
1215
1216       · IN $trigger_info: hash reference of specification of trigger to
1217         create, with structure of "trigger_info_t".
1218
1219       · RET: error code.
1220
1221       $rc = $slurm->clear_trigger($trigger_info);
1222
1223       Clear an existing event trigger.
1224
1225       · IN $trigger_info: hash reference of specification of trigger to
1226         remove, with structure of "trigger_info_t".
1227
1228       · RET: error code.
1229
1230       $resp = $slurm->get_triggers();
1231
1232       Get all event trigger information.
1233
1234       · RET: hash reference with structure of "trigger_info_msg_t". On
1235         failure "undef" is returned with errno set.
1236
1237   JOB/NODE STATE TESTING FUNCTIONS
1238       The following are functions to test job/node state, based on the macros
1239       defined in src/common/slurm_protocol_defs.h. The functions take a
1240       parameter of a hash reference of a job/node, and return a boolean
1241       value. For job, $job->{job_state} is tested. For node,
1242       $node->{node_state} is tested.
1243
1244       $cond = IS_JOB_PENDING($job);
1245
1246       $cond = IS_JOB_RUNNING($job);
1247
1248       $cond = IS_JOB_SUSPENDED($job);
1249
1250       $cond = IS_JOB_COMPLETE($job);
1251
1252       $cond = IS_JOB_CANCELLED($job);
1253
1254       $cond = IS_JOB_FAILED($job);
1255
1256       $cond = IS_JOB_TIMEOUT($job);
1257
1258       $cond = IS_JOB_NODE_FAILED($job);
1259
1260       $cond = IS_JOB_COMPLETING($job);
1261
1262       $cond = IS_JOB_CONFIGURING($job);
1263
1264       $cond = IS_JOB_STARTED($job);
1265
1266       $cond = IS_JOB_FINISHED($job);
1267
1268       $cond = IS_JOB_COMPLETED($job);
1269
1270       $cond = IS_JOB_RESIZING($job);
1271
1272       $cond = IS_NODE_UNKNOWN($node);
1273
1274       $cond = IS_NODE_DOWN($node);
1275
1276       $cond = IS_NODE_IDLE($node);
1277
1278       $cond = IS_NODE_ALLOCATED($node);
1279
1280       $cond = IS_NODE_ERROR($node);
1281
1282       $cond = IS_NODE_MIXED($node);
1283
1284       $cond = IS_NODE_FUTURE($node);
1285
1286       $cond = IS_NODE_DRAIN($node);
1287
1288       $cond = IS_NODE_DRAINING($node);
1289
1290       $cond = IS_NODE_DRAINED($node);
1291
1292       $cond = IS_NODE_COMPLETING($node);
1293
1294       $cond = IS_NODE_NO_RESPOND($node);
1295
1296       $cond = IS_NODE_POWER_SAVE($node);
1297
1298       $cond = IS_NODE_POWER_UP($node);
1299
1300       $cond = IS_NODE_FAIL($node);
1301
1302       $cond = IS_NODE_MAINT($node);
1303

EXPORT

1305       The job/node state testing functions are exported by default.
1306
1307       If ':constant' if specified, all constants are exported.
1308

AUTHOR

1317       This library is created by Hongjia Cao, <hjcao(AT)nudt.edu.cn> and
1318       Danny Auble, <da(AT)llnl.gov>. It is distributed with Slurm.
1319

COPYRIGHT AND LICENSE

1321       This library is free software; you can redistribute it and/or modify it
1322       under the same terms as Perl itself, either Perl version 5.8.4 or, at
1323       your option, any later version of Perl 5 you may have available.
1324
1325
1326
1327perl v5.30.1                      2020-01-30                          Slurm(3)