1 | /* $Id: drmaa.h 2 2009-10-12 09:51:22Z mamonski $ */ |
---|
2 | /* |
---|
3 | * FedStage DRMAA utilities library |
---|
4 | * Copyright (C) 2006-2008 FedStage Systems |
---|
5 | * |
---|
6 | * This program is free software: you can redistribute it and/or modify |
---|
7 | * it under the terms of the GNU General Public License as published by |
---|
8 | * the Free Software Foundation, either version 3 of the License, or |
---|
9 | * (at your option) any later version. |
---|
10 | * |
---|
11 | * This program is distributed in the hope that it will be useful, |
---|
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
---|
14 | * GNU General Public License for more details. |
---|
15 | * |
---|
16 | * You should have received a copy of the GNU General Public License |
---|
17 | * along with this program. If not, see <http://www.gnu.org/licenses/>. |
---|
18 | */ |
---|
19 | /* |
---|
20 | * Documentation taken from: |
---|
21 | * |
---|
22 | * Distributed Resource Management Application API C Bindings v1.0 |
---|
23 | * |
---|
24 | * Copyright (C) Global Grid Forum (2003). All Rights Reserved. |
---|
25 | * |
---|
26 | * This document and translations of it may be copied and furnished to |
---|
27 | * others, and derivative works that comment on or otherwise explain it |
---|
28 | * or assist in its implementation may be prepared, copied, published |
---|
29 | * and distributed, in whole or in part, without restriction of any kind, |
---|
30 | * provided that the above copyright notice and this paragraph are included |
---|
31 | * on all such copies and derivative works. However, this document itself |
---|
32 | * may not be modified in any way, such as by removing the copyright notice |
---|
33 | * or references to the GGF or other organizations, except as needed for the |
---|
34 | * purpose of developing Grid Recommendations in which case the procedures |
---|
35 | * for copyrights defined in the GGF Document process must be followed, |
---|
36 | * or as required to translate it into languages other than English. |
---|
37 | * |
---|
38 | * The limited permissions granted above are perpetual and will not be |
---|
39 | * revoked by the GGF or its successors or assigns. |
---|
40 | * This document and the information contained herein is provided on an |
---|
41 | * "AS IS" basis and THE GLOBAL GRID FORUM DISCLAIMS ALL WARRANTIES, EXPRESS |
---|
42 | * OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE |
---|
43 | * INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES |
---|
44 | * OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. |
---|
45 | */ |
---|
46 | |
---|
47 | /** |
---|
48 | * @file drmaa.h |
---|
49 | * DRMAA interface functions. |
---|
50 | * @author Åukasz CieÅnik <lukasz.ciesnik@fedstage.com> |
---|
51 | */ |
---|
52 | |
---|
53 | #ifndef __DRMAA_H |
---|
54 | #define __DRMAA_H |
---|
55 | |
---|
56 | #include <stddef.h> |
---|
57 | #include <stdio.h> |
---|
58 | |
---|
59 | /** @defgroup drmaa_jobt Job template operations. */ |
---|
60 | |
---|
61 | /** @defgroup drmaa DRMAA interface. */ |
---|
62 | /* @{ */ |
---|
63 | |
---|
64 | typedef struct drmaa_job_template_s drmaa_job_template_t; |
---|
65 | typedef struct drmaa_attr_names_s drmaa_attr_names_t; |
---|
66 | typedef struct drmaa_attr_values_s drmaa_attr_values_t; |
---|
67 | typedef struct drmaa_job_ids_s drmaa_job_ids_t; |
---|
68 | |
---|
69 | #define DRMAA_ATTR_BUFFER 1024 |
---|
70 | #define DRMAA_CONTACT_BUFFER 1024 |
---|
71 | #define DRMAA_DRM_SYSTEM_BUFFER 1024 |
---|
72 | #define DRMAA_DRMAA_IMPL_BUFFER 1024 |
---|
73 | #define DRMAA_ERROR_STRING_BUFFER 4096 |
---|
74 | #define DRMAA_JOBNAME_BUFFER 128 |
---|
75 | #define DRMAA_SIGNAL_BUFFER 32 |
---|
76 | |
---|
77 | #define DRMAA_TIMEOUT_NO_WAIT 0 |
---|
78 | #define DRMAA_TIMEOUT_WAIT_FOREVER -1 |
---|
79 | #define DRMAA_PS_UNDETERMINED 0x00 |
---|
80 | #define DRMAA_PS_QUEUED_ACTIVE 0x10 |
---|
81 | #define DRMAA_PS_SYSTEM_ON_HOLD 0x11 |
---|
82 | #define DRMAA_PS_USER_ON_HOLD 0x12 |
---|
83 | #define DRMAA_PS_USER_SYSTEM_ON_HOLD 0x13 |
---|
84 | #define DRMAA_PS_RUNNING 0x20 |
---|
85 | #define DRMAA_PS_SYSTEM_SUSPENDED 0x21 |
---|
86 | #define DRMAA_PS_USER_SUSPENDED 0x22 |
---|
87 | #define DRMAA_PS_USER_SYSTEM_SUSPENDED 0x23 |
---|
88 | #define DRMAA_PS_DONE 0x30 |
---|
89 | #define DRMAA_PS_FAILED 0x40 |
---|
90 | #define DRMAA_CONTROL_SUSPEND 0 |
---|
91 | #define DRMAA_CONTROL_RESUME 1 |
---|
92 | #define DRMAA_CONTROL_HOLD 2 |
---|
93 | #define DRMAA_CONTROL_RELEASE 3 |
---|
94 | #define DRMAA_CONTROL_TERMINATE 4 |
---|
95 | #define DRMAA_JOB_IDS_SESSION_ALL "DRMAA_JOB_IDS_SESSION_ALL" |
---|
96 | #define DRMAA_JOB_IDS_SESSION_ANY "DRMAA_JOB_IDS_SESSION_ANY" |
---|
97 | |
---|
98 | #define DRMAA_BLOCK_EMAIL "drmaa_block_email" |
---|
99 | #define DRMAA_DEADLINE_TIME "drmaa_deadline_time" |
---|
100 | #define DRMAA_DURATION_HLIMIT "drmaa_duration_hlimit" |
---|
101 | #define DRMAA_DURATION_SLIMIT "drmaa_duration_slimit" |
---|
102 | #define DRMAA_ERROR_PATH "drmaa_error_path" |
---|
103 | #define DRMAA_INPUT_PATH "drmaa_input_path" |
---|
104 | #define DRMAA_JOB_CATEGORY "drmaa_job_category" |
---|
105 | #define DRMAA_JOB_NAME "drmaa_job_name" |
---|
106 | #define DRMAA_JOIN_FILES "drmaa_join_files" |
---|
107 | #define DRMAA_JS_STATE "drmaa_js_state" |
---|
108 | #define DRMAA_NATIVE_SPECIFICATION "drmaa_native_specification" |
---|
109 | #define DRMAA_OUTPUT_PATH "drmaa_output_path" |
---|
110 | #define DRMAA_REMOTE_COMMAND "drmaa_remote_command" |
---|
111 | #define DRMAA_START_TIME "drmaa_start_time" |
---|
112 | #define DRMAA_TRANSFER_FILES "drmaa_transfer_files" |
---|
113 | #define DRMAA_V_ARGV "drmaa_v_argv" |
---|
114 | #define DRMAA_V_EMAIL "drmaa_v_email" |
---|
115 | #define DRMAA_V_ENV "drmaa_v_env" |
---|
116 | #define DRMAA_WCT_HLIMIT "drmaa_wct_hlimit" |
---|
117 | #define DRMAA_WCT_SLIMIT "drmaa_wct_slimit" |
---|
118 | #define DRMAA_WD "drmaa_wd" |
---|
119 | |
---|
120 | #define DRMAA_SUBMISSION_STATE_ACTIVE "drmaa_active" |
---|
121 | #define DRMAA_SUBMISSION_STATE_HOLD "drmaa_hold" |
---|
122 | #define DRMAA_PLACEHOLDER_HD "$drmaa_hd_ph$" |
---|
123 | #define DRMAA_PLACEHOLDER_WD "$drmaa_wd_ph$" |
---|
124 | #define DRMAA_PLACEHOLDER_INCR "$drmaa_incr_ph$" |
---|
125 | |
---|
126 | #define DRMAA_ERRNO_SUCCESS 0 |
---|
127 | #define DRMAA_ERRNO_INTERNAL_ERROR 1 |
---|
128 | #define DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE 2 |
---|
129 | #define DRMAA_ERRNO_AUTH_FAILURE 3 |
---|
130 | #define DRMAA_ERRNO_INVALID_ARGUMENT 4 |
---|
131 | #define DRMAA_ERRNO_NO_ACTIVE_SESSION 5 |
---|
132 | #define DRMAA_ERRNO_NO_MEMORY 6 |
---|
133 | #define DRMAA_ERRNO_INVALID_CONTACT_STRING 7 |
---|
134 | #define DRMAA_ERRNO_DEFAULT_CONTACT_STRING_ERROR 8 |
---|
135 | #define DRMAA_ERRNO_NO_DEFAULT_CONTACT_STRING_SELECTED 9 |
---|
136 | #define DRMAA_ERRNO_DRMS_INIT_FAILED 10 |
---|
137 | #define DRMAA_ERRNO_ALREADY_ACTIVE_SESSION 11 |
---|
138 | #define DRMAA_ERRNO_DRMS_EXIT_ERROR 12 |
---|
139 | #define DRMAA_ERRNO_INVALID_ATTRIBUTE_FORMAT 13 |
---|
140 | #define DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE 14 |
---|
141 | #define DRMAA_ERRNO_CONFLICTING_ATTRIBUTE_VALUES 15 |
---|
142 | #define DRMAA_ERRNO_TRY_LATER 16 |
---|
143 | #define DRMAA_ERRNO_DENIED_BY_DRM 17 |
---|
144 | #define DRMAA_ERRNO_INVALID_JOB 18 |
---|
145 | #define DRMAA_ERRNO_RESUME_INCONSISTENT_STATE 19 |
---|
146 | #define DRMAA_ERRNO_SUSPEND_INCONSISTENT_STATE 20 |
---|
147 | #define DRMAA_ERRNO_HOLD_INCONSISTENT_STATE 21 |
---|
148 | #define DRMAA_ERRNO_RELEASE_INCONSISTENT_STATE 22 |
---|
149 | #define DRMAA_ERRNO_EXIT_TIMEOUT 23 |
---|
150 | #define DRMAA_ERRNO_NO_RUSAGE 24 |
---|
151 | #define DRMAA_ERRNO_NO_MORE_ELEMENTS 25 |
---|
152 | |
---|
153 | |
---|
154 | #if defined(__cplusplus) |
---|
155 | extern "C" { |
---|
156 | #endif |
---|
157 | |
---|
158 | |
---|
159 | /** |
---|
160 | * The drmaa_init() function SHALL initialize DRMAA library and create |
---|
161 | * a new DRMAA session, using the contact parameter, if provided, to |
---|
162 | * determine to which DRMS to connect. This function MUST be called |
---|
163 | * before any other DRMAA function, except for drmaa_get_DRM_system(), |
---|
164 | * drmaa_get_DRMAA_implementation(), drmaa_get_contact(), and |
---|
165 | * drmaa_strerror(). If @a contact is @c NULL, the default DRM system |
---|
166 | * SHALL be used, provided there is only one DRMAA implementation |
---|
167 | * in the provided binary module. When there is more than one DRMAA |
---|
168 | * implementation in the binary module, drmaa_init() SHALL return |
---|
169 | * the DRMAA_ERRNO_NO_DEFAULT_CONTACT_STRING_SELECTED error code. |
---|
170 | * The drmaa_init() function SHOULD be called by only one of the threads. |
---|
171 | * The main thread is RECOMMENDED. A call by another thread SHALL return |
---|
172 | * the DRMAA_ERRNO_ALREADY_ACTIVE_SESSION error code. |
---|
173 | */ |
---|
174 | int drmaa_init( |
---|
175 | const char *contact, |
---|
176 | char *error_diagnosis, size_t error_diag_len |
---|
177 | ); |
---|
178 | |
---|
179 | /** |
---|
180 | * The drmaa_exit() function SHALL disengage from DRMAA library and |
---|
181 | * allow the DRMAA library to perform any necessary internal cleanup. |
---|
182 | * This routine SHALL end the current DRMAA session but SHALL NOT |
---|
183 | * affect any jobs (e.g, queued and running jobs SHALL remain queued and |
---|
184 | * running). drmaa_exit() SHOULD be called by only one of the threads. |
---|
185 | * The first call to call drmaa_exit() by a thread will operate normally. |
---|
186 | * All other calls from the same and other threads SHALL fail, returning |
---|
187 | * a DRMAA_ERRNO_NO_ACTIVE_SESSION error code. |
---|
188 | */ |
---|
189 | int drmaa_exit( char *error_diagnosis, size_t error_diag_len ); |
---|
190 | |
---|
191 | |
---|
192 | |
---|
193 | /** |
---|
194 | * The function drmaa_allocate_job_template() SHALL allocate a new job |
---|
195 | * template, returned in @a jt. This template is used to describe the |
---|
196 | * job to be submitted. This description is accomplished by setting the |
---|
197 | * desired scalar and vector attributes to their appropriate values. This |
---|
198 | * template is then used in the job submission process. |
---|
199 | * @addtogroup drmaa_jobt |
---|
200 | */ |
---|
201 | int drmaa_allocate_job_template( |
---|
202 | drmaa_job_template_t **jt, |
---|
203 | char *error_diagnosis, size_t error_diag_len |
---|
204 | ); |
---|
205 | |
---|
206 | /** |
---|
207 | * The function drmaa_delete_job_template() SHALL free the job template |
---|
208 | * pointed to by @a jt. |
---|
209 | * @addtogroup drmaa_jobt |
---|
210 | */ |
---|
211 | int drmaa_delete_job_template( |
---|
212 | drmaa_job_template_t *jt, |
---|
213 | char *error_diagnosis, size_t error_diag_len |
---|
214 | ); |
---|
215 | |
---|
216 | /** |
---|
217 | * The function drmaa_set_attribute() SHALL set the value of the scalar |
---|
218 | * attribute, @a name, in the job template, @a jt, to the value, @a value. |
---|
219 | * @addtogroup drmaa_jobt |
---|
220 | */ |
---|
221 | int drmaa_set_attribute( |
---|
222 | drmaa_job_template_t *jt, |
---|
223 | const char *name, const char *value, |
---|
224 | char *error_diagnosis, size_t error_diag_len |
---|
225 | ); |
---|
226 | |
---|
227 | /** |
---|
228 | * The function drmaa_get_attribute() SHALL fill the @a value buffer with |
---|
229 | * up to @a value_len characters of the scalar attribute, @a name's, value |
---|
230 | * in the given job template. |
---|
231 | * @addtogroup drmaa_jobt |
---|
232 | */ |
---|
233 | int drmaa_get_attribute( |
---|
234 | drmaa_job_template_t *jt, |
---|
235 | const char *name, char *value, size_t value_len, |
---|
236 | char *error_diagnosis, size_t error_diag_len |
---|
237 | ); |
---|
238 | |
---|
239 | /** |
---|
240 | * The function drmaa_set_vector_attribute() SHALL set the vector attribute, |
---|
241 | * @a name, in the job template, @a jt, to the value(s), @a value. The DRMAA |
---|
242 | * implementation MUST accept value values that are arrays of one or more |
---|
243 | * strings terminated by a @c NULL entry. |
---|
244 | * @addtogroup drmaa_jobt |
---|
245 | */ |
---|
246 | int drmaa_set_vector_attribute( |
---|
247 | drmaa_job_template_t *jt, |
---|
248 | const char *name, const char *value[], |
---|
249 | char *error_diagnosis, size_t error_diag_len |
---|
250 | ); |
---|
251 | |
---|
252 | /** |
---|
253 | * The function drmaa_get_vector_attribute() SHALL store in @a values an |
---|
254 | * opaque values string vector containing the values of the vector attribute, |
---|
255 | * @a name's, value in the given job template. |
---|
256 | * @addtogroup drmaa_jobt |
---|
257 | */ |
---|
258 | int drmaa_get_vector_attribute( |
---|
259 | drmaa_job_template_t *jt, |
---|
260 | const char *name, drmaa_attr_values_t **values, |
---|
261 | char *error_diagnosis, size_t error_diag_len |
---|
262 | ); |
---|
263 | |
---|
264 | |
---|
265 | |
---|
266 | /** |
---|
267 | * The function drmaa_get_attribute_names() SHALL return the set of supported |
---|
268 | * scalar attribute names in an opaque names string vector stored in |
---|
269 | * @a values. This vector SHALL include all required scalar attributes, all |
---|
270 | * supported optional scalar attributes, all DRM-specific scalar attributes, |
---|
271 | * and no unsupported optional attributes. |
---|
272 | */ |
---|
273 | int drmaa_get_attribute_names( |
---|
274 | drmaa_attr_names_t **values, |
---|
275 | char *error_diagnosis, size_t error_diag_len |
---|
276 | ); |
---|
277 | |
---|
278 | /** |
---|
279 | * The function drmaa_get_vector_attribute_names() SHALL return the set |
---|
280 | * of supported vector attribute names in an opaque names string vector |
---|
281 | * stored in @a values. This vector SHALL include all required vector |
---|
282 | * attributes, all supported optional vector attributes, all DRM-specific |
---|
283 | * vector attributes, and no unsupported optional attributes. |
---|
284 | */ |
---|
285 | int drmaa_get_vector_attribute_names( |
---|
286 | drmaa_attr_names_t **values, |
---|
287 | char *error_diagnosis, size_t error_diag_len |
---|
288 | ); |
---|
289 | |
---|
290 | /** |
---|
291 | * @defgroup drmaa_viter Vector iteration functions. |
---|
292 | * @ingroup drmaa |
---|
293 | * |
---|
294 | * The drmaa_get_next_<i>X</i>() functions SHALL store up to @a value_len |
---|
295 | * bytes of the next attribute name / attribute value / job identifier |
---|
296 | * from the @a values opaque string vector in the @a value buffer. |
---|
297 | * The opaque string vector's internal iterator SHALL then be moved forward |
---|
298 | * to the next entry. If there are no more values those functions return |
---|
299 | * @ref DRMAA_ERRNO_INVALID_ARGUMENT (but this is outside DRMAA specification). |
---|
300 | * |
---|
301 | * The drmaa_get_num_<i>X</i>() functions SHALL store the number of elements |
---|
302 | * in the space provided by @a size. |
---|
303 | * |
---|
304 | * The drmaa_release_<i>X</i>() functions free the memory used by the |
---|
305 | * @a values opaque string vector. All memory used by strings contained |
---|
306 | * therein is also freed. |
---|
307 | */ |
---|
308 | /* @addtogroup drmaa_viter @{ */ |
---|
309 | int drmaa_get_next_attr_name( drmaa_attr_names_t* values, |
---|
310 | char *value, size_t value_len ); |
---|
311 | int drmaa_get_next_attr_value( drmaa_attr_values_t* values, |
---|
312 | char *value, size_t value_len ); |
---|
313 | int drmaa_get_next_job_id( drmaa_job_ids_t* values, |
---|
314 | char *value, size_t value_len ); |
---|
315 | int drmaa_get_num_attr_names( drmaa_attr_names_t* values, size_t *size ); |
---|
316 | int drmaa_get_num_attr_values(drmaa_attr_values_t* values, size_t *size ); |
---|
317 | int drmaa_get_num_job_ids( drmaa_job_ids_t* values, size_t *size ); |
---|
318 | void drmaa_release_attr_names( drmaa_attr_names_t* values ); |
---|
319 | void drmaa_release_attr_values( drmaa_attr_values_t* values ); |
---|
320 | void drmaa_release_job_ids( drmaa_job_ids_t* values ); |
---|
321 | /* @} */ |
---|
322 | |
---|
323 | /** |
---|
324 | * The drmaa_run_job() function submits a single job with the attributes |
---|
325 | * defined in the job template, @a jt. Upon success, up to @a job_id_len |
---|
326 | * characters of the submitted job's job identifier are stored in the buffer, |
---|
327 | * @a job_id. |
---|
328 | */ |
---|
329 | int drmaa_run_job( |
---|
330 | char *job_id, size_t job_id_len, const drmaa_job_template_t *jt, |
---|
331 | char *error_diagnosis, size_t error_diag_len |
---|
332 | ); |
---|
333 | |
---|
334 | /** |
---|
335 | * The drmaa_run_bulk_jobs() function submits a set of parametric jobs which |
---|
336 | * can be run concurrently. The attributes defined in the job template, |
---|
337 | * @a jt are used for every parametric job in the set. Each job in the |
---|
338 | * set is identical except for it's index. The first parametric job has an |
---|
339 | * index equal to @a start. The next job has an index equal to @a start + |
---|
340 | * @a incr, and so on. The last job has an index equal to <code>start + n * |
---|
341 | * incr</code>, where @c n is equal to <code>(end - start) / incr</code>. |
---|
342 | * Note that the value of the last job's index may not be equal to end if the |
---|
343 | * difference between @a start and @a end is not evenly divisble by @a incr. |
---|
344 | * The smallest valid value for @a start is 1. The largest valid value for |
---|
345 | * @a end is 2147483647 (2^31-1). The @a start value must be less than or |
---|
346 | * equal to the @a end value, and only positive index numbers are allowed. |
---|
347 | * The index number can be determined by the job in an implementation |
---|
348 | * specific fashion. On success, an opaque job id string vector containing |
---|
349 | * job identifiers for all submitted jobs SHALL be returned into @a job_ids. |
---|
350 | * The job identifiers in the opaque job id string vector can be extracted |
---|
351 | * using the drmaa_get_next_job_id() function. The caller is responsible |
---|
352 | * for releasing the opaque job id string vector returned into @a job_ids |
---|
353 | * using the drmaa_release_job_ids() function. |
---|
354 | */ |
---|
355 | int drmaa_run_bulk_jobs( |
---|
356 | drmaa_job_ids_t **jobids, |
---|
357 | const drmaa_job_template_t *jt, |
---|
358 | int start, int end, int incr, |
---|
359 | char *error_diagnosis, size_t error_diag_len |
---|
360 | ); |
---|
361 | |
---|
362 | /** |
---|
363 | * The drmaa_control() function SHALL enact the action indicated |
---|
364 | * by @a action on the job specified by the job identifier, @a jobid. |
---|
365 | * The action parameter's value may be one of the following: |
---|
366 | * - DRMAA_CONTROL_SUSPEND |
---|
367 | * - DRMAA_CONTROL_RESUME |
---|
368 | * - DRMAA_CONTROL_HOLD |
---|
369 | * - DRMAA_CONTROL_RELEASE |
---|
370 | * - DRMAA_CONTROL_TERMINATE |
---|
371 | * The drmaa_control() function SHALL return after the DRM system has |
---|
372 | * acknowledged the command, not necessarily after the desired action has |
---|
373 | * been performed. If @a jobid is DRMAA_JOB_IDS_SESSION_ALL, this function |
---|
374 | * SHALL perform the specified action on all jobs submitted during this |
---|
375 | * session as of this function is called. |
---|
376 | */ |
---|
377 | int drmaa_control( |
---|
378 | const char *job_id, int action, |
---|
379 | char *error_diagnosis, size_t error_diag_len |
---|
380 | ); |
---|
381 | |
---|
382 | /** |
---|
383 | * The drmaa_job_ps() function SHALL store in @a remote_ps the program |
---|
384 | * status of the job identified by @a job_id. The possible values of |
---|
385 | * a program's staus are: |
---|
386 | * - DRMAA_PS_UNDETERMINED |
---|
387 | * - DRMAA_PS_QUEUED_ACTIVE |
---|
388 | * - DRMAA_PS_SYSTEM_ON_HOLD |
---|
389 | * - DRMAA_PS_USER_ON_HOLD |
---|
390 | * - DRMAA_PS_USER_SYSTEM_ON_HOLD |
---|
391 | * - DRMAA_PS_RUNNING |
---|
392 | * - DRMAA_PS_SYSTEM_SUSPENDED |
---|
393 | * - DRMAA_PS_USER_SUSPENDED |
---|
394 | * - DRMAA_PS_DONE |
---|
395 | * - DRMAA_PS_FAILED |
---|
396 | * Terminated jobs have a status of DRMAA_PS_FAILED. |
---|
397 | */ |
---|
398 | int drmaa_job_ps( |
---|
399 | const char *job_id, int *remote_ps, |
---|
400 | char *error_diagnosis, size_t error_diag_len |
---|
401 | ); |
---|
402 | |
---|
403 | /** |
---|
404 | * The drmaa_synchronize() function SHALL cause the calling thread to |
---|
405 | * block until all jobs specified by @a job_ids have finished execution. |
---|
406 | * If @a job_ids contains DRMAA_JOB_IDS_SESSION_ALL, then this function |
---|
407 | * SHALL wait for all jobs submitted during this DRMAA session as of the |
---|
408 | * point in time when drmaa_synchronize() is called. To avoid thread race |
---|
409 | * conditions in multithreaded applications, the DRMAA implementation user |
---|
410 | * should explicitly synchronize this call with any other job submission |
---|
411 | * calls or control calls that may change the number of remote jobs. |
---|
412 | * |
---|
413 | * The @a timeout parameter value indicates how many seconds to remain |
---|
414 | * blocked in this call waiting for results to become available, before |
---|
415 | * returning with a DRMAA_ERRNO_EXIT_TIMEOUT error code. The value, |
---|
416 | * DRMAA_TIMEOUT_WAIT_FOREVER, MAY be specified to wait indefinitely for |
---|
417 | * a result. The value, DRMAA_TIMEOUT_NO_WAIT, MAY be specified to return |
---|
418 | * immediately with a DRMAA_ERRNO_EXIT_TIMEOUT error code if no result is |
---|
419 | * available. If the call exits before the timeout has elapsed, all the |
---|
420 | * jobs have been waited on or there was an interrupt. The caller should |
---|
421 | * check system time before and after this call in order to be sure of how |
---|
422 | * much time has passed. The @a dispose parameter specifies how to treat |
---|
423 | * the reaping of the remote job's internal data record, which includes a |
---|
424 | * record of the job's consumption of system resources during its execution |
---|
425 | * and other statistical information. If the @a dispose parameter's value |
---|
426 | * is 1, the DRMAA implementation SHALL dispose of the job's data record at |
---|
427 | * the end of the drmaa_synchroniize() call. If the @a dispose parameter's |
---|
428 | * value is 0, the data record SHALL be left for future access via the |
---|
429 | * drmaa_wait() method. |
---|
430 | */ |
---|
431 | int drmaa_synchronize( |
---|
432 | const char *job_ids[], signed long timeout, int dispose, |
---|
433 | char *error_diagnosis, size_t error_diag_len |
---|
434 | ); |
---|
435 | |
---|
436 | /** |
---|
437 | * The drmaa_wait() function SHALL wait for a job identified by @a job_id |
---|
438 | * to finish execution or fail. If the special string, JOB_IDS_SESSION_ANY, |
---|
439 | * is provided as the job_id, this function will wait for any job from the |
---|
440 | * session to finish execution or fail. In this case, any job for which exit |
---|
441 | * status information is available will satisfy the requirement, including |
---|
442 | * jobs which preivously finished but have never been the subject of a |
---|
443 | * drmaa_wait() call. This routine is modeled on the @c wait3 POSIX routine. |
---|
444 | * |
---|
445 | * The @a timeout parameter value indicates how many seconds |
---|
446 | * to remain blocked in this call waiting for a result, before |
---|
447 | * returning with a DRMAA_ERRNO_EXIT_TIMEOUT error code. The value, |
---|
448 | * DRMAA_TIMEOUT_WAIT_FOREVER, MAY be specified to wait indefinitely for |
---|
449 | * a result. The value, DRMAA_TIMEOUT_NO_WAIT, MAY be specified to return |
---|
450 | * immediately with a DRMAA_ERRNO_EXIT_TIMEOUT error code if no result is |
---|
451 | * available. If the call exits before the timeout has elapsed, the job |
---|
452 | * has been successfully waited on or there was an interrupt. The caller |
---|
453 | * should check system time before and after this call in order to be sure |
---|
454 | * of how much time has passed. |
---|
455 | * |
---|
456 | * Upon success, drmaa_wait() fills @a job_id_out with up to @a |
---|
457 | * job_id_out_len characters of the waited job's id, stat with the |
---|
458 | * a code that includes information about the conditions under which |
---|
459 | * the job terminated, and @a rusage with an array of <name>=<value> |
---|
460 | * strings that describe the amount of resources consumed by the job |
---|
461 | * and are implementation defined. The @a stat parameter is further |
---|
462 | * described below. The @a rusage parameter's values may be accessed via |
---|
463 | * drmaa_get_next_attr_value(). |
---|
464 | * |
---|
465 | * The drmaa_wait() function reaps job data records on a successful |
---|
466 | * call, so any subsequent calls to drmaa_wait() will fail, returning |
---|
467 | * a DRMAA_ERRNO_INVALID_JOB error code, meaning that the job's data |
---|
468 | * record has already been reaped. This error code is the same as |
---|
469 | * if the job were unknown. If drmaa_wait() exists due to a timeout, |
---|
470 | * DRMAA_ERRNO_EXIT_TIMEOUT is returned and no rusage information is reaped. |
---|
471 | * (The only case where drmaa_wait() can be successfully called on a single |
---|
472 | * job more than once is when the previous call(s) to drmaa_wait() returned |
---|
473 | * DRMAA_ERRNO_EXIT_TIMEOUT.) |
---|
474 | * |
---|
475 | * The stat parameter, set by a successful call to drmaa_wait(), is used |
---|
476 | * to retrieve further input about the exit condition of the waited |
---|
477 | * job, identified by job_id_out, through the following functions: |
---|
478 | * drmaa_wifexited(), drmaa_wexitstatus(), drmaa_wifsignaled(), |
---|
479 | * drmaa_wtermsig(),drmaa_wcoredump() and drmaa_wifaborted(). |
---|
480 | */ |
---|
481 | int drmaa_wait( |
---|
482 | const char *job_id, |
---|
483 | char *job_id_out, size_t job_id_out_len, int *stat, |
---|
484 | signed long timeout, drmaa_attr_values_t **rusage, |
---|
485 | char *error_diagnosis, size_t error_diag_len |
---|
486 | ); |
---|
487 | |
---|
488 | int drmaa_wifexited( int *exited, int stat, |
---|
489 | char *error_diagnosis, size_t error_diag_len ); |
---|
490 | int drmaa_wexitstatus( int *exit_status, int stat, |
---|
491 | char *error_diagnosis, size_t error_diag_len ); |
---|
492 | int drmaa_wifsignaled( int *signaled, int stat, |
---|
493 | char *error_diagnosis, size_t error_diag_len ); |
---|
494 | int drmaa_wtermsig( char *signal, size_t signal_len, int stat, |
---|
495 | char *error_diagnosis, size_t error_diag_len ); |
---|
496 | int drmaa_wcoredump( int *core_dumped, int stat, |
---|
497 | char *error_diagnosis, size_t error_diag_len ); |
---|
498 | int drmaa_wifaborted( int *aborted, int stat, |
---|
499 | char *error_diagnosis, size_t error_diag_len ); |
---|
500 | |
---|
501 | /** |
---|
502 | * The drmaa_strerror() function SHALL return the error string describing |
---|
503 | * the DRMAA error number @a drmaa_errno. |
---|
504 | */ |
---|
505 | const char *drmaa_strerror( int drmaa_errno ); |
---|
506 | |
---|
507 | /** |
---|
508 | * The drmaa_get_contact() function, if called before drmaa_init(), SHALL |
---|
509 | * return a string containing a comma-delimited list of default DRMAA |
---|
510 | * implementation contacts strings, one per DRM implementation provided. |
---|
511 | * If called after drmaa_init(), drmaa_get_contacts() SHALL return the |
---|
512 | * contact string for the DRM system for which the library has been |
---|
513 | * initialized. |
---|
514 | */ |
---|
515 | int drmaa_get_contact( char *contact, size_t contact_len, |
---|
516 | char *error_diagnosis, size_t error_diag_len ); |
---|
517 | |
---|
518 | /** |
---|
519 | * The drmaa_version() function SHALL set major and minor to the major and |
---|
520 | * minor versions of the DRMAA C binding specification implemented by the |
---|
521 | * DRMAA implementation. |
---|
522 | */ |
---|
523 | int drmaa_version( unsigned int *major, unsigned int *minor, |
---|
524 | char *error_diagnosis, size_t error_diag_len ); |
---|
525 | |
---|
526 | /** |
---|
527 | * The drmaa_get_DRM_system() function, if called before drmaa_init(), |
---|
528 | * SHALL return a string containing a comma-delimited list of DRM system |
---|
529 | * identifiers, one per DRM system implementation provided. If called after |
---|
530 | * drmaa_init(), drmaa_get_DRM_system() SHALL return the selected DRM system. |
---|
531 | */ |
---|
532 | int drmaa_get_DRM_system( char *drm_system, size_t drm_system_len, |
---|
533 | char *error_diagnosis, size_t error_diag_len ); |
---|
534 | |
---|
535 | /** |
---|
536 | * The drmaa_get_DRMAA_implementation() function, if called before |
---|
537 | * drmaa_init(), SHALL return a string containing a comma-delimited list of |
---|
538 | * DRMAA implementations, one per DRMAA implementation provided. If called |
---|
539 | * after drmaa_init(), drmaa_get_DRMAA_implementation() SHALL return the |
---|
540 | * selected DRMAA implementation. |
---|
541 | */ |
---|
542 | int drmaa_get_DRMAA_implementation( char *drmaa_impl, size_t drmaa_impl_len, |
---|
543 | char *error_diagnosis, size_t error_diag_len ); |
---|
544 | |
---|
545 | /* @} */ |
---|
546 | |
---|
547 | |
---|
548 | |
---|
549 | |
---|
550 | int |
---|
551 | drmaa_read_configuration_file( |
---|
552 | const char *filename, int must_exist, |
---|
553 | char *error_diagnosis, size_t error_diag_len |
---|
554 | ); |
---|
555 | |
---|
556 | int |
---|
557 | drmaa_read_configuration( |
---|
558 | const char *configuration, size_t conf_len, |
---|
559 | char *error_diagnosis, size_t error_diag_len |
---|
560 | ); |
---|
561 | |
---|
562 | |
---|
563 | #if defined(__cplusplus) |
---|
564 | } /* extern "C" */ |
---|
565 | #endif |
---|
566 | |
---|
567 | #endif /* __DRMAA_H */ |
---|
568 | |
---|