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