2 * simgrid.msg.Msg.java 1.00 07/05/01
4 * Copyright 2006,2007 Martin Quinson, Malek Cherier
7 * This program is free software; you can redistribute
8 * it and/or modify it under the terms of the license
9 *(GNU LGPL) which comes with this package.
16 import org.xml.sax.helpers.*;
19 * MSG was the first distributed programming environment
20 * provided within SimGrid. While almost realistic, it
21 * remains quite simple.
22 * This class contains all the declaration of the natives methods
24 * All of these methods are statics. You can't directly use these methods
25 * but it is recommanded to use the classes Process, Host, Task and ParallelTask
26 * of the package to build your application.
28 * @author Abdelmalek Cherier
29 * @author Martin Quinson
30 * @version 1.00, 07/05/01
38 public final class Msg {
40 * The natively implemented method to get the last error code of the simulation.
42 * @return The last error code of the simulation.
44 final static native int getErrCode();
47 * Errors returned by the method Msg.getErrCode().
50 /* Everything is right. Keep on goin the way !
53 public static final int SUCCESS = 0;
55 /* Something must be not perfectly clean. But I
56 * may be paranoid freak... !
58 public static final int WARNING = 1;
60 /* There has been a problem during you task treansfer.
61 * Either the network is down or the remote host has
64 public static final int TRANSFERT_FAILURE = 2;
67 * System shutdown. The host on which you are running
68 * has just been rebooted. Free your datastructures and
71 public static final int HOST_FAILURE = 3;
74 * Cancelled task. This task has been cancelled by somebody !
76 public static final int TASK_CANCELLLED = 4;
79 * You've done something wrong. You'd better look at it...
81 public static final int FATAL_ERROR = 5;
84 * Staticaly load the SIMGRID4JAVA library
85 * which contains all native functions used in here
89 System.loadLibrary("libSimgrid4java");
90 } catch(UnsatisfiedLinkError e){
91 System.err.println("Cannot load simgrid4java library : ");
93 System.err.println("Please check your LD_LIBRARY_PATH, "+
94 "or copy the library to the current directory");
99 /******************************************************************
100 * The natively implemented methods connected to the MSG Process *
101 ******************************************************************/
104 * The natively implemented method to create an MSG process.
106 * @param process The java process object to bind with the MSG native process.
107 * @param host A valid (binded) host where create the process.
109 * @exception simgrid.msg.JniException if JNI stuff goes wrong.
111 * @see Process constructors.
114 void processCreate(Process process, Host host) throws JniException;
117 * The natively implemented method to kill all the process of the simulation.
119 * @param resetPID Should we reset the PID numbers. A negative number means no reset
120 * and a positive number will be used to set the PID of the next newly
123 * @return The function returns the PID of the next created process.
125 final static native int processKillAll(int resetPID);
128 * The natively implemented method to suspend an MSG process.
130 * @param process The valid (binded with a native process) java process to suspend.
132 * @exception JniException if something goes wrong with JNI
133 * NativeException if the SimGrid native code failed.
135 * @see Process.pause()
137 final static native void processSuspend(Process process)
138 throws JniException, NativeException;
141 * The natively implemented method to kill a MSG process.
143 * @param process The valid (binded with a native process) java process to kill.
145 * @see Process.kill()
147 final static native void processKill(Process process)
151 * The natively implemented method to resume a suspended MSG process.
153 * @param process The valid (binded with a native process) java process to resume.
155 * @exception JniException if something goes wrong with JNI
156 * NativeException if the SimGrid native code failed.
158 * @see Process.restart()
160 final static native void processResume(Process process)
161 throws JniException, NativeException;
164 * The natively implemented method to test if MSG process is suspended.
166 * @param process The valid (binded with a native process) java process to test.
168 * @return If the process is suspended the method retuns true. Otherwise the
169 * method returns false.
171 * @exception JniException if something goes wrong with JNI
173 * @see Process.isSuspended()
175 final static native boolean processIsSuspended(Process process) throws JniException;
178 * The natively implemented method to get the host of a MSG process.
180 * @param process The valid (binded with a native process) java process to get the host.
182 * @return The method returns the host where the process is running.
184 * @exception JniException if something goes wrong with JNI
185 * NativeException if the SimGrid native code failed.
187 * @see Process.getHost()
189 final static native Host processGetHost(Process process)
190 throws JniException, NativeException;
193 * The natively implemented method to get a MSG process from his PID.
195 * @param PID The PID of the process to get.
197 * @return The process with the specified PID.
199 * @exception NativeException if the SimGrid native code failed.
201 * @see Process.getFromPID()
203 final static native Process processFromPID(int PID) throws NativeException;
206 * The natively implemented method to get the PID of a MSG process.
208 * @param process The valid (binded with a native process) java process to get the PID.
210 * @return The PID of the specified process.
212 * @exception NativeException if the SimGrid native code failed.
214 * @see Process.getPID()
216 final static native int processGetPID(Process process) throws NativeException;
219 * The natively implemented method to get the PPID of a MSG process.
221 * @param process The valid (binded with a native process) java process to get the PID.
223 * @return The PPID of the specified process.
225 * @exception NativeException if the SimGrid native code failed.
227 * @see Process.getPPID()
229 final static native int processGetPPID(Process process) throws NativeException;
232 * The natively implemented method to get the current running process.
234 * @return The current process.
236 * @exception NativeException if the SimGrid native code failed.
238 * @see Process.currentProcess()
240 final static native Process processSelf() throws NativeException;
243 * The natively implemented method to get the current running process PID.
245 * @return The PID of the current process.
247 * @see Process.currentProcessPID()
249 final static native int processSelfPID();
252 * The natively implemented method to get the current running process PPID.
254 * @return The PPID of the current process.
256 * @see Process.currentProcessPPID()
258 final static native int processSelfPPID();
261 * The natively implemented method to migrate a process from his currnet host to a new host.
263 * @param process The (valid) process to migrate.
264 * @param host A (valid) host where move the process.
266 * @exception JniException if something goes wrong with JNI
267 * NativeException if the SimGrid native code failed.
269 * @see Process.migrate()
270 * @see Host.getByName()
272 final static native void processChangeHost(Process process,Host host)
273 throws JniException, NativeException;
276 * Process synchronization. The process wait the signal of the simulator to start.
278 * @exception JniException if something goes wrong with JNI
280 final static native void waitSignal(Process process) throws JniException;
283 * The natively implemented native to request the current process to sleep
284 * until time seconds have elapsed.
286 * @param seconds The time the current process must sleep.
288 * @exception NativeException if the SimGrid native code failed.
290 * @see Process.waitFor()
292 final static native void processWaitFor(double seconds) throws NativeException;
295 * The natively implemented native method to exit a process.
297 * @exception JniException if something goes wrong with JNI
299 * @see Process.exit()
301 final static native void processExit(Process process) throws JniException;
304 /******************************************************************
305 * The natively implemented methods connected to the MSG host *
306 ******************************************************************/
309 * The natively implemented method to get an host from his name.
311 * @param name The name of the host to get.
313 * @return The host having the specified name.
315 * @exception JniException if something goes wrong with JNI
316 * HostNotFoundException if there is no such host
317 * NativeException if the SimGrid native code failed.
319 * @see Host.getByName()
321 final static native Host hostGetByName(String name)
322 throws JniException, HostNotFoundException, NativeException;
325 * The natively implemented method to get the name of an MSG host.
327 * @param host The host (valid) to get the name.
329 * @return The name of the specified host.
331 * @exception JniException if something goes wrong with JNI
333 * @see Host.getName()
335 final static native String hostGetName(Host host) throws JniException;
338 * The natively implemented method to get the number of hosts of the simulation.
340 * @return The number of hosts of the simulation.
342 * @see Host.getNumber()
344 final static native int hostGetNumber();
347 * The natively implemented method to get the host of the current runing process.
349 * @return The host of the current running process.
351 * @exception JniException if something goes wrong with JNI
353 * @see Host.currentHost()
355 final static native Host hostSelf() throws JniException;
358 * The natively implemented method to get the speed of a MSG host.
360 * @param host The host to get the host.
362 * @return The speed of the specified host.
364 * @exception JniException if something goes wrong with JNI
366 * @see Host.getSpeed()
369 final static native double hostGetSpeed(Host host) throws JniException;
372 * The natively implemented native method to test if an host is avail.
374 * @param host The host to test.
376 * @return If the host is avail the method returns true.
377 * Otherwise the method returns false.
379 * @exception JniException if something goes wrong with JNI
381 * @see Host.isAvail()
383 final static native boolean hostIsAvail(Host host) throws JniException;
386 * The natively implemented native method to get all the hosts of the simulation.
388 * @exception JniException if something goes wrong with JNI
390 * @return A array which contains all the hosts of simulation.
393 final static native Host[] allHosts() throws JniException;
396 * The natively implemented native method to get the number of running tasks on a host.
398 * @param The host concerned by the operation.
400 * @return The number of running tasks.
402 * @exception JniException if something goes wrong with JNI
405 final static native int hostGetLoad(Host host) throws JniException;
407 /******************************************************************
408 * The natively implemented methods connected to the MSG task *
409 ******************************************************************/
412 * The natively implemented method to create a MSG task.
414 * @param name The name of th task.
415 * @param computeDuration A value of the processing amount (in flop) needed
416 * to process the task. If 0, then it cannot be executed
417 * with the execute() method. This value has to be >= 0.
418 * @param messageSize A value of amount of data (in bytes) needed to transfert
419 * this task. If 0, then it cannot be transfered this task.
420 * If 0, then it cannot be transfered with the get() and put()
421 * methods. This value has to be >= 0.
422 * @param task The java task object to bind with the native task to create.
424 * @exception JniException if something goes wrong with JNI
425 * NullPointerException if the specified name is null.
426 * IllegalArgumentException if compute duration <0 or message size <0
430 final static native void taskCreate(Task task,String name,double computeDuration, double messageSize)
431 throws JniException, NullPointerException, IllegalArgumentException;
434 * The natively implemented method to get the sender of a task.
436 * @param task The task (valid) to get the sender.
438 * @return The sender of the task.
440 * @exception InvalidTaskException is the specified task is not valid. A task
441 * is invalid if it is not binded with a native task.
443 * @see Task.getSender()
445 final static native Process taskGetSender(Task task) throws JniException;
448 * The natively implementd method to get the source of a task.
450 * @param task The task to get the source.
452 * @return The source of the task.
454 * @exception InvalidTaskException is the specified task is not valid. A task
455 * is invalid if it is not binded with a native task.
457 * @see Task.getSource()
459 final static native Host taskGetSource(Task task) throws JniException, NativeException;
462 * The natively implemented method to get the name of the task.
464 * @param task The task to get the name.
466 * @return The name of the specified task.
468 * @exception InvalidTaskException is the specified task is not valid. A task
469 * is invalid if it is not binded with a native task.
471 * @see Task.getName()
473 final static native String taskGetName(Task task) throws JniException;
476 * The natively implemented method to cancel a task.
478 * @param task The task to cancel.
480 * @exception InvalidTaskException if the specified task is not valid. A task
481 * is invalid if it is not binded with a native task.
482 * MsgException if the cancelation failed.
484 * @see Task.cancel().
486 final static native void taskCancel(Task task) throws JniException, NativeException;
489 * The natively implemented method to get the computing amount of the task.
491 * @param task The task to get the computing amount.
493 * @return The computing amount of the specified task.
495 * @exception InvalidTaskException if the specified task is not valid. A task
496 * is invalid if it is not binded with a native task.
497 * MsgException if the cancelation failed.
499 * @see Task.getComputeDuration()
501 final static native double taskGetComputeDuration(Task task) throws JniException;
504 * The natively implemented method to get the remaining computation
506 * @param task The task to get the remaining computation.
508 * @return The remaining computation of the specified task.
510 * @exception InvalidTaskException if the specified task is not valid. A task
511 * is invalid if it is not binded with a native task.
512 * MsgException if the cancelation failed.
514 * @see Task.getRemainingDuration()
516 final static native double taskGetRemainingDuration(Task task) throws JniException;
519 * The natively implemented method to set the priority of a task.
521 * @param task The task to set the prirotity
523 * @param priority The new priority of the specified task.
525 * @exception InvalidTaskException if the specified task is not valid. A task
526 * is invalid if it is not binded with a native task.
527 * MsgException if the cancelation failed.
529 * @see Task.setPriority()
531 final static native void taskSetPriority(Task task,double priority) throws JniException;
534 * The natively implemented method to destroy a MSG task.
536 * @param The task to destroy.
538 * @exception InvalidTaskException is the specified task is not valid. A task
539 * is invalid if it is not binded with a native task.
540 * MsgException if the destruction failed.
542 * @see Task.destroy()
544 final static native void taskDestroy(Task task) throws JniException, NativeException;
547 * The natively implemented method to execute a MSG task.
549 * @param task The task to execute.
551 * @exception InvalidTaskException is the specified task is not valid. A task
552 * is invalid if it is not binded with a native task.
553 * MsgException if the destruction failed.
555 * @see Task.execute()
557 final static native void taskExecute(Task task) throws JniException, NativeException;
561 /**************************************************************************
562 * The natively implemented methods connected to the MSG parallel task *
563 ***************************************************************************/
566 * The natively implemented method to create a MSG parallel task.
568 * @param name The name of the parallel task.
569 * @param hosts The list of hosts implied by the parallel task.
570 * @param computeDurations The total number of operations that have to be performed
572 * @param messageSizes An array of doubles
574 * @see ParallelTask.create()
576 final static native void parallelTaskCreate(ParallelTask parallelTask, String name,
577 Host[] hosts, double[] computeDurations, double[] messageSizes)
578 throws JniException, NullPointerException, IllegalArgumentException;
581 * The natively implemented method to get the sender of a parallel task.
583 * @param parallelTask The parallel task (valid) to get the sender.
585 * @return The sender of the parallel task.
587 * @see ParallelTask.getSender()
589 final static native Process parallelTaskGetSender(ParallelTask parallelTask) throws JniException;
592 * The natively implementd method to get the source of a parallel task.
594 * @param parallelTask The parallel task to get the source.
596 * @return The source of the parallel task.
598 * @see ParallelTask.getSource()
600 final static native Host parallelTaskGetSource(ParallelTask parallelTask) throws JniException;
603 * The natively implemented method to get the name of the parallel task.
605 * @param parallelTask The parallel task to get the name.
607 * @return The name of the specified parallel task.
609 * @see ParallelTask.getName()
611 final static native String parallelTaskGetName(ParallelTask parallelTask) throws JniException;
614 * The natively implemented method to cancel a parallel task.
616 * @param parallelTask The parallel task to cancel.
618 * @see ParallelTask.cancel().
620 final static native void parallelTaskCancel(ParallelTask parallelTask) throws JniException,NativeException;
623 * The natively implemented method to get the computing amount of the task.
625 * @param parallelTask The parallel task to get the computing amount.
627 * @return The computing amount of the specified parallel task.
629 * @see ParallelTask.getComputeDuration()
631 final static native double parallelTaskGetComputeDuration(ParallelTask parallelTask) throws JniException;
634 * The natively implemented method to get the remaining computation
636 * @param parallelTask The parallel task to get the remaining computation.
638 * @return The remaining computation of the specified parallel task.
640 * @see ParallelTask.getRemainingDuration()
642 final static native double parallelTaskGetRemainingDuration(ParallelTask parallelTask) throws JniException;
645 * The natively implemented method to set the priority of a parallel task.
647 * @param parallelTask The parallel task to set the prirotity
649 * @param priority The new priority of the specified parallel task.
651 * @see ParallelTask.setPriority()
653 final static native void parallelTaskSetPriority(ParallelTask parallelTask,double priority) throws JniException;
656 * The natively implemented method to destroy a MSG parallel task.
658 * @param parallelTask The parallel task to destroy.
660 * @see ParallelTask.destroy()
662 final static native void parallelTaskDestroy(ParallelTask parallelTask) throws JniException,NativeException;
665 * The natively implemented method to execute a MSG parallel task.
667 * @param parallelTask The parallel task to execute.
669 * @see ParallelTask.execute()
671 final static native void parallelTaskExecute(ParallelTask parallelTask) throws JniException, NativeException;
673 /******************************************************************
674 * The natively implemented methods connected to the MSG channel *
675 ******************************************************************/
678 * The natively implemented method to listen on the channel and wait for receiving a task.
680 * @param channel The channel to listen
682 * @return The task readed from the channel.
684 * @exception MsgException if the listening operation failed.
688 final static native Task channelGet(Channel channel) throws JniException,NativeException;
691 * The natively implemented method to listen on the channel and wait for receiving a task with a timeout.
693 * @param channel The channel to listen.
694 * @param timeout The timeout of the listening.
696 * @return The task readed from the channel.
698 * @exception MsgException if the listening operation failed.
700 * @see Channel.getWithTimeout()
703 final static native Task channelGetWithTimeout(Channel channel,double timeout) throws JniException,NativeException;
707 * The natively implemented method to listen on the channel of a specific host.
709 * @param channel The channel to listen.
711 * @param host The specific host.
713 * @return The task readed from the channel of the specific host.
715 * @exception InvalidHostException if the specified host is not valid.
716 * MsgException if the listening operation failed.
718 * @see Channel.getFromHost()
720 final static native Task channelGetFromHost(Channel channel,Host host) throws JniException,NativeException;
723 * The natively implemented method to test whether there is a pending communication on the channel.
725 * @param channel The channel concerned by the operation.
727 * @return The method returns true if there is a pending communication on the specified
728 * channel. Otherwise the method returns false.
730 * @see Channel.hasPendingCommunication()
732 final static native boolean channelHasPendingCommunication(Channel channel) throws JniException;
735 * The natively implemented method to test whether there is a pending communication on a
736 * channel, and who sent it.
738 * @param The channel concerned by the operation.
740 * @return The method returns -1 if there is no pending communication and
741 * the PID of the process who sent it otherwise.
743 * @see Channel.getCummunicatingProcess()
745 final static native int channelGetCommunicatingProcess(Channel channel) throws JniException;
748 * The natively implemented method to get the number of tasks waiting to be received on a
749 * channel and sent by a host.
751 * @param channel The channel concerned by the operation.
753 * @param host The sender of the tasks.
755 * @return The number of tasks waiting to be received on a channel
756 * and sent by the specified host.
758 * @exception InvalidHostException if the specified host is not valid.
760 * @see Channel.getHostWaiting()
762 final static native int channelGetHostWaitingTasks(Channel channel,Host host) throws JniException;
765 * The natively implemented method to put a task on the channel of an host.
767 * @param channel The channel where to put the task.
768 * @param task The task to put.
769 * @param host The host of the specified channel.
771 * @exception InvalidTaskException if the task is not valid.
772 * InvalidHostException if the host is not valid.
773 * MsgException if the operation failed.
777 final static native void channelPut(Channel channel,Task task,Host host) throws JniException,NativeException;
780 * The natively implemented method to put a task on a channel of an host (with a timeout
781 * on the waiting of the destination host) and waits for the end of the transmission.
783 * @param channel The channel where to put the task.
784 * @param task The task to put.
785 * @param host The host containing the channel.
786 * @param timeout The timeout of the transmission.
788 * @exception InvalidTaskException if the task is not valid.
789 * InvalidHostException if the host is not valid.
790 * MsgException if the operation failed.
792 * @see Channel.putWithTimeout()
794 final static native void channelPutWithTimeout(Channel channel,Task task,Host host,double timeout) throws JniException,NativeException;
797 * The natively implemented method to put a task on channel with a bounded transmition
800 * @param channel The channel where to put the task.
801 * @param task The task to put.
802 * @param host The host containing the channel.
803 * @param max_rate The bounded transmition rate.
805 * @exception InvalidTaskException if the task is not valid.
806 * InvalidHostException if the host is not valid.
807 * MsgException if the operation failed.
809 * @see Channel.putBounded()
811 final static native void channelPutBounded(Channel channel,Task task,Host host,double max_rate) throws JniException,NativeException;
814 * The natively implemented method to wait for at most timeout seconds for a task reception
815 * on channel. The PID is updated with the PID of the first process.
817 * @param channel The channel concerned by the operation.
818 * @param timeout The maximum time to wait for a task before
821 * @exception MsgException if the reception operation failed.
823 * @see Channel.wait()
825 final static native int channelWait(Channel channel, double timeout) throws JniException,NativeException;
828 * The natively implemented method to set the number of channel used by all the process
831 * @param channelNumber The channel number of the process.
833 * @see Channel.setNumber()
835 final static native void channelSetNumber(int channelNumber);
838 * The natively implemented method to get the number of channel of the process of the simulation.
840 * @return The number of channel per process.
842 * @see Channel.getNumber()
844 final static native int channelGetNumber();
846 /*********************************************************************************
847 * Additional native methods *
848 **********************************************************************************/
851 * The natively implemented method to get the simulation time.
853 * @param The simulation time.
855 public final static native double getClock();
857 public final static native void pajeOutput(String pajeFile);
860 public final static native void info(String s);
862 /*********************************************************************
863 * The natively implemented methods connected to the MSG simulation *
864 *********************************************************************/
867 * The natively implemented method to initialize a MSG simulation.
869 * @param args The arguments of the command line of the simulation.
873 public final static native void init(String[] args);
876 * Run the MSG simulation, and cleanup everything afterward.
878 * If you want to chain simulations in the same process, you
879 * should call again createEnvironment and deployApplication afterward.
881 * @see MSG_run, MSG_clean
883 public final static native void run() throws NativeException;
886 * The native implemented method to create the environment of the simulation.
888 * @param platformFile The XML file which contains the description of the environment of the simulation
891 public final static native void createEnvironment(String platformFile) throws NativeException;
895 * The method to deploy the simulation.
897 * @param appFile The XML file which contains the description of the application to deploy.
901 public static void deployApplication(String platformFile) {
903 Class c = Class.forName("com.sun.org.apache.xerces.internal.parsers.SAXParser");
904 XMLReader reader = (XMLReader)c.newInstance();
905 reader.setEntityResolver(new DTDResolver());
906 ApplicationHandler handler = new ApplicationHandler();
907 reader.setContentHandler(handler);
908 reader.setFeature("http://xml.org/sax/features/validation", false);
909 reader.parse(platformFile);
911 } catch(Exception e) {
912 /* FIXME: do not swallow exception ! */
913 System.out.println("Exception in Msg.launchApplication()");
914 System.out.println(e);
920 static public void main(String[]args) throws MsgException {
921 /* initialize the MSG simulation. Must be done before anything else (even logging). */
924 if(args.length < 2) {
926 Msg.info("Usage: Msg platform_file deployment_file");
930 /* specify the number of channel for the process of the simulation. */
931 Channel.setNumber(1);
933 /* Load the platform and deploy the application */
934 Msg.createEnvironment(args[0]);
935 Msg.deployApplication(args[1]);
937 /* Execute the simulation */