src/java/simgrid/msg/Channel.java

   1 /*
   2  * $Id$
   3  *
   4  * Copyright 2006,2007 Martin Quinson, Malek Cherier
   5  * All right reserved.
   6  *
   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.
  10  */
  11
  12 package simgrid.msg;
  13
  14 /**
  15  * For convenience, the simulator provides the notion of
  16  * channel that is close to the tag notion in MPI. A channel
  17  * is not a socket. It doesn't need to be opened neither closed.
  18  * It rather corresponds to the ports opened on the different
  19  * machines.
  20  *
  21  * @author  Abdelmalek Cherier
  22  * @author  Martin Quinson
  23  * @version $Id$
  24  * @see Task
  25  * @since SimGrid 3.3
  26  * @since JDK1.5011
  27  */
  28 public final class Channel
  29 {
  30         /**
  31          * The channel identifier (as a port number in the TCP protocol.
  32          */
  33         private int id;
  34
  35         private Channel() {} /* disable the default constructor */
  36
  37         /**
  38          * Construct the channel with the specified identifier.
  39          *
  40          * @param id                    The channel identifier.
  41          */
  42         public Channel(int id){
  43                 this.id = id;
  44         }
  45
  46         /**
  47          * This static method sets the number of channels for all the hosts
  48          * of the simulation.
  49          *
  50          * param channelNumber  The channel number to set.
  51          */
  52         public static void setNumber(int channelNumber) {
  53                 Msg.channelSetNumber(channelNumber);
  54         }
  55
  56         /**
  57          * This static method gets the number of channel of the simulation.
  58          *
  59          * @return                              The channel numbers used in the simulation.
  60          */
  61         public static int getNumber() {
  62                 return Msg.channelGetNumber();
  63         }
  64
  65         /** Returns the identifier of the channel */
  66         public int getId() {
  67                 return this.id;
  68         }
  69
  70         /**
  71          * Listen on the channel and wait for receiving a task.
  72          *
  73          * @return                              The task readed from the channel.
  74          *
  75          */
  76         public Task get() throws JniException,NativeException {
  77                 return Msg.channelGet(this);
  78         }
  79
  80         /**
  81          * Listen on the channel and wait for receiving a task with a timeout.
  82          *
  83          * @param timeout               The timeout of the listening.
  84          *
  85          * @return                              The task readed from the channel.
  86          *
  87          * @exception                   NativeException if the listening operation failed.
  88          */
  89         public Task getWithTimeout(double timeout) throws JniException, NativeException{
  90                 return Msg.channelGetWithTimeout(this,timeout);
  91         }
  92
  93         /**
  94          * Listen on the channel and wait for receiving a task from a host.
  95          *
  96          * @param host                  The host.
  97          *
  98          * @return                              The task readed from the channel.
  99          *
 100          * @exception                   InvalidHostException if the specified host is not valid.
 101          *                                              MsgException if the listening operation failed.
 102          *
 103          * @see                                 Host
 104          */
 105         public Task getFromHost(Host host) throws NativeException, JniException{
 106                 return Msg.channelGetFromHost(this,host);
 107         }
 108
 109         /**
 110          * This method tests whether there is a pending communication on the channel.
 111          *
 112          * @return                              This method returns true if there is a pending communication
 113          *                                              on the channel. Otherwise the method returns false.
 114          */
 115         public boolean hasPendingCommunication() throws NativeException, JniException{
 116                 return Msg.channelHasPendingCommunication(this);
 117         }
 118
 119         /**
 120          * This method tests whether there is a pending communication on a
 121          * channel, and who sent it.
 122          *
 123          * @return                              The method returns -1 if there is no pending
 124          *                                              communication and the PID of the process who sent it otherwise
 125          */
 126         public int getCommunicatingProcess() throws JniException{
 127                 return Msg.channelGetCommunicatingProcess(this) ;
 128         }
 129
 130         /**
 131          * Wait for at most timeout seconds for a task reception
 132          * on channel. The PID is updated with the PID of the first process.
 133          *
 134          * @param timeout               The maximum time to wait for a task before
 135          *                                              giving up.
 136          * @return                              The PID of the first process to send a task.
 137          *
 138          * @exception                   MsgException if the reception failed.
 139          */
 140         public int wait(double timeout) throws NativeException, JniException{
 141                 return Msg.channelWait(this,timeout);
 142         }
 143
 144         /**
 145          * This method returns the number of tasks waiting to be received on a
 146          * channel and sent by a host.
 147          *
 148          * @param host                  The host that is to be watched.
 149          *
 150          * @return                              The number of tasks waiting to be received on a channel
 151          *                                              and sent by a host.
 152          *
 153          * @exception                   InvalidHostException if the specified host is not valid.
 154          */
 155         public int getHostWaitingTasks(Host host)  throws JniException{
 156                 return Msg.channelGetHostWaitingTasks(this,host);
 157         }
 158
 159         /**
 160          * This method puts a task on a channel of an host and waits for the end of the
 161          * transmission.
 162          *
 163          * @param task                  The task to put.
 164          * @param host                  The destinated host.
 165          *
 166          * @exception                   InvalidTaskException if the task is not valid.
 167          *                                              InvalidHostException if the host is not valid.
 168          *                                              MsgException if the operation failed.
 169          */
 170         public void put(Task task,Host host) throws NativeException, JniException {
 171                 Msg.channelPut(this,task,host);
 172         }
 173
 174         /**
 175          * This method puts a task on a channel of an  host (with a timeout on the waiting
 176          * of the destination host) and waits for the end of the transmission.
 177          *
 178          * @param task                  The task to put.
 179          * @param host                  The destination where to put the task.
 180          * @param timeout               The timeout of the transmission.
 181          *
 182          * @exception                   InvalidTaskException if the task is not valid.
 183          *                                              InvalidHostException if the host is not valid.
 184          *                                              MsgException if the operation failed.
 185          */
 186         public void putWithTimeout(Task task,Host host,double timeout) throws NativeException, JniException {
 187                 Msg.channelPutWithTimeout(this,task,host,timeout);
 188         }
 189
 190         /**
 191          * This method does exactly the same as put() but with a bounded transmition
 192          * rate.
 193          *
 194          * @param task                  The task to put.
 195          * @param host                  The destination where to put the task.
 196          * @param maxRate               The bounded transmition rate.
 197          *
 198          * @exception                   InvalidTaskException if the task is not valid.
 199          *                                              InvalidHostException if the host is not valid.
 200          *                                              MsgException if the operation failed.
 201          */
 202         public void putBounded(Task task,Host host,double maxRate) throws NativeException, JniException {
 203                 Msg.channelPutBounded(this,task,host,maxRate);
 204         }
 205 }