1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
|
<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
drmaa_synchronize, drmaa_wait, drmaa_wifexited,
drmaa_wexitstatus, drmaa_wifsignaled, drmaa_wtermsig,
drmaa_wcoredump, drmaa_wifaborted - Waiting for jobs to fin-
ish
SYNOPSIS
#include "drmaa.h"
int drmaa_synchronize(
const char *job_ids[],
signed long timeout,
int dispose,
char *error_diagnosis,
size_t error_diag_len
);
int drmaa_wait(
const char *job_id,
char *job_id_out,
size_t job_id_out_len,
int *stat,
signed long timeout,
drmaa_attr_values_t **rusage,
char *error_diagnosis,
size_t error_diagnois_len
);
int drmaa_wifaborted(
int *aborted,
int stat,
char *error_diagnosis,
size_t error_diag_len
);
int drmaa_wifexited(
int *exited,
int stat,
char *error_diagnosis,
size_t error_diag_len
);
int drmaa_wifsignaled(
int *signaled,
int stat,
char *error_diagnosis,
size_t error_diag_len
);
int drmaa_wcoredump(
int *core_dumped,
int stat,
char *error_diagnosis,
size_t error_diag_len
);
int drmaa_wexitstatus(
int *exit_status,
int stat,
char *error_diagnosis,
size_t error_diag_len
);
int drmaa_wtermsig(
char *signal,
size_t signal_len,
int stat,
char *error_diagnosis,
size_t error_diag_len
);
DESCRIPTION
The drmaa_synchronize() function blocks the calling thread
until all jobs specified in <I>job</I>_<I>ids</I> have failed or finished
execution. If <I>job</I>_<I>ids</I> contains 'DRMAA_JOB_IDS_SESSION_ALL',
then this function waits for all jobs submitted during this
DRMAA session. The <I>job</I>_<I>ids</I> pointer array must be <I>NULL</I> ter-
minated.
To prevent blocking indefinitely in this call, the caller
may use the <I>timeout</I>, specifying how many seconds to wait for
this call to complete before timing out. The special value
DRMAA_TIMEOUT_WAIT_FOREVER can be used to wait indefinitely
for a result. The special value DRMAA_TIMEOUT_NO_WAIT can be
used to return immediately. If the call exits before <I>timeout</I>
seconds, all the specified jobs have completed or the cal-
ling thread received an interrupt. In both cases, the
return code is DRMAA_ERRNO_EXIT_TIMEOUT.
The <I>dispose</I> parameter specifies how to treat reaping infor-
mation. If '0' is passed to this parameter, job finish
information will still be available when <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> is
used. If '1' is passed, <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> will be unable to
access this job's finish information.
drmaa_wait()
The drmaa_wait() function blocks the calling thread until a
job fails or finishes execution. This routine is modeled on
the <B><A HREF="../htmlman3/wait4.html">wait4(3)</A></B> routine. If the special string
'DRMAA_JOB_IDS_SESSION_ANY' is passed as <I>job</I>_<I>id</I>, this rou-
tine will wait for any job from the session. Otherwise the
<I>job</I>_<I>id</I> must be the job identifier of a job or array job task
that was submitted during the session.
To prevent blocking indefinitely in this call, the caller
may use <I>timeout</I>, specifying how many seconds to wait for
this call to complete before timing out. The special value
DRMAA_TIMEOUT_WAIT_FOREVER can be to wait indefinitely for a
result. The special value DRMAA_TIMEOUT_NO_WAIT can be used
to return immediately. If the call exits before <I>timeout</I>
seconds have passed, all the specified jobs have completed
or the calling thread received an interrupt. In both cases,
the return code is DRMAA_ERRNO_EXIT_TIMEOUT.
The routine reaps jobs on a successful call, so any subse-
quent calls to <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> will fail returning a
DRMAA_ERRNO_INVALID_JOB error, meaning that the job has
already been reaped. This error is the same as if the job
were unknown. Returning due to an elapsed timeout or an
interrupt does not cause the job information to be reaped.
This means that, in this case, it is possible to issue
<B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> multiple times for the same <I>job</I>_<I>id</I>.
If <I>job</I>_<I>id</I>_<I>out</I> is not a null pointer, then on return from a
successful <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> call, up to <I>job</I>_<I>id</I>_<I>out</I>_<I>len</I> charac-
ters from the job id of the failed or finished job are
returned.
If <I>stat</I> is not a null pointer, then on return from a suc-
cessful <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> call, the status of the job is stored
in the integer pointed to by <I>stat</I>. <I>stat</I> indicates whether
job failed or finished and other information. The informa-
tion encoded in the integer value can be accessed via
<B><A HREF="../htmlman3/drmaa_wifaborted.html">drmaa_wifaborted(3)</A></B> <B><A HREF="../htmlman3/drmaa_wifexited.html">drmaa_wifexited(3)</A></B> <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B>
<B><A HREF="../htmlman3/drmaa_wcoredump.html">drmaa_wcoredump(3)</A></B> <B><A HREF="../htmlman3/drmaa_wexitstatus.html">drmaa_wexitstatus(3)</A></B> <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>.
If <I>rusage</I> is not a null pointer, then on return from a suc-
cessful <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> call, a summary of the resources used
by the terminated job is returned in form of a DRMAA values
string vector. The entries in the DRMAA values string vec-
tor can be extracted using <B><A HREF="../htmlman3/drmaa_get_next_attr_value.html">drmaa_get_next_attr_value(3)</A></B>.
Each string returned by <B><A HREF="../htmlman3/drmaa_get_next_attr_value.html">drmaa_get_next_attr_value(3)</A></B> will be
of the format <name>=<value>, where <name> and <value>
specify name and amount of resources consumed by the job,
respectively. See <B><A HREF="../htmlman5/accounting.html">accounting(5)</A></B> for an explanation of the
resource information.
drmaa_wifaborted()
The drmaa_wifaborted() function evaluates into the integer
pointed to by <I>aborted</I> a non-zero value if <I>stat</I> was returned
from a job that ended before entering the running state.
drmaa_wifexited()
The drmaa_wifexited() function evaluates into the integer
pointed to by <I>exited</I> a non-zero value if <I>stat</I> was returned
from a job that terminated normally. A zero value can also
indicate that although the job has terminated normally, an
exit status is not available, or that it is not known
whether the job terminated normally. In both cases
<B><A HREF="../htmlman3/drmaa_wexitstatus.html">drmaa_wexitstatus(3)</A></B> will not provide exit status informa-
tion. A non-zero value returned in <I>exited</I> indicates more
detailed diagnosis can be provided by means of
<B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B>, <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B> and
<B><A HREF="../htmlman3/drmaa_wcoredump.html">drmaa_wcoredump(3)</A></B>.
drmaa_wifsignaled()
The drmaa_wifsignaled() function evaluates into the integer
pointed to by <I>signaled</I> a non-zero value if <I>stat</I> was returned
for a job that terminated due to the receipt of a signal. A
zero value can also indicate that although the job has ter-
minated due to the receipt of a signal, the signal is not
available, or it is not known whether the job terminated due
to the receipt of a signal. In both cases <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>
will not provide signal information. A non-zero value
returned in <I>signaled</I> indicates signal information can be
retrieved by means of <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>.
drmaa_wcoredump()
If <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B> returned a non-zero value in the
<I>signaled</I> parameter, the drmaa_wcoredump() function evaluates
into the integer pointed to by <I>core</I>_<I>dumped</I> a non-zero value
if a core image of the terminated job was created.
drmaa_wexitstatus()
If <B><A HREF="../htmlman3/drmaa_wifexited.html">drmaa_wifexited(3)</A></B> returned a non-zero value in the
<I>exited</I> parameter, the drmaa_wexitstatus() function evaluates
into the integer pointed to by <I>exit</I>_<I>code</I> the exit code that
the job passed to <B><A HREF="../htmlman2/exit.html">exit(2)</A></B> or the value that the child pro-
cess returned from main.
drmaa_wtermsig()
If <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B> returned a non-zero value in the
<I>signaled</I> parameter, the drmaa_wtermsig() function evaluates
into <I>signal</I> up to <I>signal</I>_<I>len</I> characters of a string
representation of the signal that caused the termination of
the job. For signals declared by POSIX.1, the symbolic names
are returned (e.g., SIGABRT, SIGALRM). For signals not
declared by POSIX, any other string may be returned.
ENVIRONMENTAL VARIABLES
SGE_ROOT Specifies the location of the Grid Engine
standard configuration files.
SGE_CELL If set, specifies the default Grid Engine
cell to be used. To address a Grid Engine
cell Grid Engine uses (in the order of pre-
cedence):
The name of the cell specified in the
environment variable SGE_CELL, if it is
set.
The name of the default cell, i.e.
default.
SGE_DEBUG_LEVEL
If set, specifies that debug information
should be written to stderr. In addition the
level of detail in which debug information is
generated is defined.
SGE_QMASTER_PORT
If set, specifies the tcp port on which
<B><A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A></B> is expected to listen for com-
munication requests. Most installations will
use a services map entry instead to define
that port.
RETURN VALUES
Upon successful completion, drmaa_run_job(),
drmaa_run_bulk_jobs(), and drmaa_get_next_job_id() return
DRMAA_ERRNO_SUCCESS. Other values indicate an error. Up to
<I>error</I>_<I>diag</I>_<I>len</I> characters of error related diagnosis infor-
mation is then provided in the buffer <I>error</I>_<I>diagnosis</I>.
ERRORS
The drmaa_synchronize(), drmaa_wait(), drmaa_wifexited(),
drmaa_wexitstatus(), drmaa_wifsignaled(), drmaa_wtermsig(),
drmaa_wcoredump(), and drmaa_wifaborted() will fail if:
DRMAA_ERRNO_INTERNAL_ERROR
Unexpected or internal DRMAA error, like system call
failure, etc.
DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
Could not contact DRM system for this request.
DRMAA_ERRNO_AUTH_FAILURE
The specified request is not processed successfully due to
authorization failure.
DRMAA_ERRNO_INVALID_ARGUMENT
The input value for an argument is invalid.
DRMAA_ERRNO_NO_ACTIVE_SESSION
Failed because there is no active session.
DRMAA_ERRNO_NO_MEMORY
Failed allocating memory.
The drmaa_synchronize() and drmaa_wait() functions will fail
if:
DRMAA_ERRNO_EXIT_TIMEOUT
Time-out condition.
DRMAA_ERRNO_INVALID_JOB
The job specified by the does not exist.
The drmaa_wait() will fail if:
DRMAA_ERRNO_NO_RUSAGE
This error code is returned by drmaa_wait() when a job has
finished but no rusage and stat data could be provided.
SEE ALSO
<B><A HREF="../htmlman3/drmaa_submit.html">drmaa_submit(3)</A></B>.
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
|
