1 //******************************************************************************
2 //
3 // File: JobFrontendRef.java
4 // Package: edu.rit.pj.cluster
5 // Unit: Interface edu.rit.pj.cluster.JobFrontendRef
6 //
7 // This Java source file is copyright (C) 2012 by Alan Kaminsky. All rights
8 // reserved. For further information, contact the author, Alan Kaminsky, at
9 // ark@cs.rit.edu.
10 //
11 // This Java source file is part of the Parallel Java Library ("PJ"). PJ is free
12 // software; you can redistribute it and/or modify it under the terms of the GNU
13 // General Public License as published by the Free Software Foundation; either
14 // version 3 of the License, or (at your option) any later version.
15 //
16 // PJ is distributed in the hope that it will be useful, but WITHOUT ANY
17 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
18 // A PARTICULAR PURPOSE. See the GNU General Public License for more details.
19 //
20 // Linking this library statically or dynamically with other modules is making a
21 // combined work based on this library. Thus, the terms and conditions of the GNU
22 // General Public License cover the whole combination.
23 //
24 // As a special exception, the copyright holders of this library give you
25 // permission to link this library with independent modules to produce an
26 // executable, regardless of the license terms of these independent modules, and
27 // to copy and distribute the resulting executable under terms of your choice,
28 // provided that you also meet, for each linked independent module, the terms
29 // and conditions of the license of that module. An independent module is a module
30 // which is not derived from or based on this library. If you modify this library,
31 // you may extend this exception to your version of the library, but you are not
32 // obligated to do so. If you do not wish to do so, delete this exception
33 // statement from your version.
34 //
35 // A copy of the GNU General Public License is provided in the file gpl.txt. You
36 // may also obtain a copy of the GNU General Public License on the World Wide
37 // Web at http://www.gnu.org/licenses/gpl.html.
38 //
39 //******************************************************************************
40 package edu.rit.pj.cluster;
41
42 import java.io.File;
43 import java.io.IOException;
44 import java.net.InetSocketAddress;
45
46 /**
47 * Interface JobFrontendRef specifies the interface for the PJ job frontend
48 * process.
49 *
50 * @author Alan Kaminsky
51 * @version 20-Jun-2012
52 */
53 public interface JobFrontendRef {
54
55 // Exported operations.
56 /**
57 * Assign a backend process to the job.
58 *
59 * @param theJobScheduler Job Scheduler that is calling this method.
60 * @param name Backend node name.
61 * @param host Host name for SSH remote login.
62 * @param jvm Full pathname of Java Virtual Machine.
63 * @param jvmflags Array of JVM command line flags.
64 * @param classpath Java class path for PJ Library.
65 * @param shellCommand Shell command string.
66 * @param Nt Number of CPUs assigned to the process.
67 * @exception IOException Thrown if an I/O error occurred.
68 * @throws java.io.IOException if any.
69 */
70 public void assignBackend(JobSchedulerRef theJobScheduler,
71 String name,
72 String host,
73 String jvm,
74 String classpath,
75 String[] jvmflags,
76 String shellCommand,
77 int Nt)
78 throws IOException;
79
80 /**
81 * Assign a job number to the job. The host name for the job frontend's
82 * middleware channel group is also specified.
83 *
84 * @param theJobScheduler Job Scheduler that is calling this method.
85 * @param jobnum Job number.
86 * @param pjhost Host name for middleware channel group.
87 * @exception IOException Thrown if an I/O error occurred.
88 * @throws java.io.IOException if any.
89 */
90 public void assignJobNumber(JobSchedulerRef theJobScheduler,
91 int jobnum,
92 String pjhost)
93 throws IOException;
94
95 /**
96 * Cancel the job.
97 *
98 * @param theJobScheduler Job Scheduler that is calling this method.
99 * @param errmsg Error message string.
100 * @exception IOException Thrown if an I/O error occurred.
101 * @throws java.io.IOException if any.
102 */
103 public void cancelJob(JobSchedulerRef theJobScheduler,
104 String errmsg)
105 throws IOException;
106
107 /**
108 * Renew the lease on the job.
109 *
110 * @param theJobScheduler Job Scheduler that is calling this method.
111 * @exception IOException Thrown if an I/O error occurred.
112 * @throws java.io.IOException if any.
113 */
114 public void renewLease(JobSchedulerRef theJobScheduler)
115 throws IOException;
116
117 /**
118 * Report that a backend process has finished executing the job.
119 *
120 * @param theJobBackend Job Backend that is calling this method.
121 * @exception IOException Thrown if an I/O error occurred.
122 * @throws java.io.IOException if any.
123 */
124 public void backendFinished(JobBackendRef theJobBackend)
125 throws IOException;
126
127 /**
128 * Report that a backend process is ready to commence executing the job.
129 *
130 * @param theJobBackend Job Backend that is calling this method.
131 * @param rank Rank of the job backend process.
132 * @param middlewareAddress Host/port to which the job backend process is
133 * listening for middleware messages.
134 * @param worldAddress Host/port to which the job backend process is
135 * listening for the world communicator.
136 * @param frontendAddress Host/port to which the job backend process is
137 * listening for the frontend communicator, or null if the frontend
138 * communicator does not exist.
139 * @exception IOException Thrown if an I/O error occurred.
140 * @throws java.io.IOException if any.
141 */
142 public void backendReady(JobBackendRef theJobBackend,
143 int rank,
144 InetSocketAddress middlewareAddress,
145 InetSocketAddress worldAddress,
146 InetSocketAddress frontendAddress)
147 throws IOException;
148
149 /**
150 * Cancel the job.
151 *
152 * @param theJobBackend Job Backend that is calling this method.
153 * @param errmsg Error message string.
154 * @exception IOException Thrown if an I/O error occurred.
155 * @throws java.io.IOException if any.
156 */
157 public void cancelJob(JobBackendRef theJobBackend,
158 String errmsg)
159 throws IOException;
160
161 /**
162 * Renew the lease on the job.
163 *
164 * @param theJobBackend Job Backend that is calling this method.
165 * @exception IOException Thrown if an I/O error occurred.
166 * @throws java.io.IOException if any.
167 */
168 public void renewLease(JobBackendRef theJobBackend)
169 throws IOException;
170
171 /**
172 * Request the given resource from this job frontend's class loader.
173 *
174 * @param theJobBackend Job Backend that is calling this method.
175 * @param resourceName Resource name.
176 * @exception IOException Thrown if an I/O error occurred.
177 * @throws java.io.IOException if any.
178 */
179 public void requestResource(JobBackendRef theJobBackend,
180 String resourceName)
181 throws IOException;
182
183 /**
184 * Open the given output file for writing or appending.
185 *
186 * @param theJobBackend Job Backend that is calling this method.
187 * @param bfd Backend file descriptor.
188 * @param file File.
189 * @param append True to append, false to overwrite.
190 * @exception IOException Thrown if an I/O error occurred.
191 * @throws java.io.IOException if any.
192 */
193 public void outputFileOpen(JobBackendRef theJobBackend,
194 int bfd,
195 File file,
196 boolean append)
197 throws IOException;
198
199 /**
200 * Write the given bytes to the given output file. <code>ffd</code> = 1 refers
201 * to the job's standard output stream; <code>ffd</code> = 2 refers to the job's
202 * standard error stream; other values refer to a previously opened file.
203 *
204 * @param theJobBackend Job Backend that is calling this method.
205 * @param ffd Frontend file descriptor.
206 * @param buf Array of bytes to write.
207 * @param off Index of first byte to write.
208 * @param len Number of bytes to write.
209 * @exception IOException Thrown if an I/O error occurred.
210 * @throws java.io.IOException if any.
211 */
212 public void outputFileWrite(JobBackendRef theJobBackend,
213 int ffd,
214 byte[] buf,
215 int off,
216 int len)
217 throws IOException;
218
219 /**
220 * Flush accumulated bytes to the given output file.
221 *
222 * @param theJobBackend Job Backend that is calling this method.
223 * @param ffd Frontend file descriptor.
224 * @exception IOException Thrown if an I/O error occurred.
225 * @throws java.io.IOException if any.
226 */
227 public void outputFileFlush(JobBackendRef theJobBackend,
228 int ffd)
229 throws IOException;
230
231 /**
232 * Close the given output file.
233 *
234 * @param theJobBackend Job Backend that is calling this method.
235 * @param ffd Frontend file descriptor.
236 * @exception IOException Thrown if an I/O error occurred.
237 * @throws java.io.IOException if any.
238 */
239 public void outputFileClose(JobBackendRef theJobBackend,
240 int ffd)
241 throws IOException;
242
243 /**
244 * Open the given input file for reading.
245 *
246 * @param theJobBackend Job Backend that is calling this method.
247 * @param bfd Backend file descriptor.
248 * @param file File.
249 * @exception IOException Thrown if an I/O error occurred.
250 * @throws java.io.IOException if any.
251 */
252 public void inputFileOpen(JobBackendRef theJobBackend,
253 int bfd,
254 File file)
255 throws IOException;
256
257 /**
258 * Read bytes from the given input file. <code>ffd</code> = 1 refers to the
259 * job's standard input stream; other values refer to a previously opened
260 * file.
261 *
262 * @param theJobBackend Job Backend that is calling this method.
263 * @param ffd Frontend file descriptor.
264 * @param len Number of bytes to read.
265 * @exception IOException Thrown if an I/O error occurred.
266 * @throws java.io.IOException if any.
267 */
268 public void inputFileRead(JobBackendRef theJobBackend,
269 int ffd,
270 int len)
271 throws IOException;
272
273 /**
274 * Skip bytes from the given input file.
275 *
276 * @param theJobBackend Job Backend that is calling this method.
277 * @param ffd Frontend file descriptor.
278 * @param len Number of bytes to skip.
279 * @exception IOException Thrown if an I/O error occurred.
280 * @throws java.io.IOException if any.
281 */
282 public void inputFileSkip(JobBackendRef theJobBackend,
283 int ffd,
284 long len)
285 throws IOException;
286
287 /**
288 * Close the given input file.
289 *
290 * @param theJobBackend Job Backend that is calling this method.
291 * @param ffd Frontend file descriptor.
292 * @exception IOException Thrown if an I/O error occurred.
293 * @throws java.io.IOException if any.
294 */
295 public void inputFileClose(JobBackendRef theJobBackend,
296 int ffd)
297 throws IOException;
298
299 /**
300 * Report a comment for a process.
301 *
302 * @param theJobBackend Job backend that is calling this method.
303 * @param rank Process rank.
304 * @param comment Comment string.
305 * @exception IOException Thrown if an I/O error occurred.
306 * @throws java.io.IOException if any.
307 */
308 public void reportComment(JobBackendRef theJobBackend,
309 int rank,
310 String comment)
311 throws IOException;
312
313 /**
314 * Close communication with this Job Frontend.
315 */
316 public void close();
317
318 }