001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.io.network.group.api.task;
020
021import org.apache.reef.annotations.audience.TaskSide;
022import org.apache.reef.io.network.group.api.operators.Broadcast;
023import org.apache.reef.io.network.group.api.operators.Gather;
024import org.apache.reef.io.network.group.api.operators.Reduce;
025import org.apache.reef.io.network.group.api.GroupChanges;
026import org.apache.reef.io.network.group.api.operators.Scatter;
027import org.apache.reef.io.network.group.impl.driver.TopologySimpleNode;
028import org.apache.reef.io.network.group.impl.task.CommunicationGroupClientImpl;
029import org.apache.reef.tang.annotations.DefaultImplementation;
030import org.apache.reef.tang.annotations.Name;
031import org.apache.reef.wake.Identifier;
032
033import java.util.List;
034
035/**
036 * The Task side interface of a communication group.
037 * Lets one get the operators configured for this task
038 * and use them for communication between tasks configured
039 * in this communication group
040 */
041@TaskSide
042@DefaultImplementation(value = CommunicationGroupClientImpl.class)
043public interface CommunicationGroupClient {
044
045  /**
046   * @return The name configured on this communication group
047   */
048  Class<? extends Name<String>> getName();
049
050  /**
051   * The broadcast sender configured on this communication group.
052   * with the given oepratorName
053   *
054   * @param operatorName
055   * @return
056   */
057  Broadcast.Sender getBroadcastSender(Class<? extends Name<String>> operatorName);
058
059  /**
060   * The broadcast receiver configured on this communication group.
061   * with the given oepratorName
062   *
063   * @param operatorName
064   * @return
065   */
066  Broadcast.Receiver getBroadcastReceiver(Class<? extends Name<String>> operatorName);
067
068  /**
069   * The reduce receiver configured on this communication group.
070   * with the given operatorName
071   *
072   * @param operatorName
073   * @return
074   */
075  Reduce.Receiver getReduceReceiver(Class<? extends Name<String>> operatorName);
076
077  /**
078   * The reduce sender configured on this communication group.
079   * with the given operatorName
080   *
081   * @param operatorName
082   * @return
083   */
084  Reduce.Sender getReduceSender(Class<? extends Name<String>> operatorName);
085
086  /**
087   * Return the scatter sender configured on this communication group.
088   * {@code operatorName} is used to specify the scatter sender to return.
089   *
090   * @param operatorName
091   * @return
092   */
093  Scatter.Sender getScatterSender(Class<? extends Name<String>> operatorName);
094
095  /**
096   * Return the scatter receiver configured on this communication group.
097   * {@code operatorName} is used to specify the scatter receiver to return.
098   *
099   * @param operatorName
100   * @return
101   */
102  Scatter.Receiver getScatterReceiver(Class<? extends Name<String>> operatorName);
103
104  /**
105   * Return the gather receiver configured on this communication group.
106   * {@code operatorName} is used to specify the gather receiver to return.
107   *
108   * @param operatorName
109   * @return
110   */
111  Gather.Receiver getGatherReceiver(Class<? extends Name<String>> operatorName);
112
113  /**
114   * Return the gather sender configured on this communication group.
115   * {@code operatorName} is used to specify the gather sender to return.
116   *
117   * @param operatorName
118   * @return
119   */
120  Gather.Sender getGatherSender(Class<? extends Name<String>> operatorName);
121
122  /**
123   * @return Changes in topology of this communication group since the last time
124   * this method was called
125   */
126  GroupChanges getTopologyChanges();
127
128  /**
129   * @return list of current active tasks, last updated during updateTopology()
130   */
131  List<Identifier> getActiveSlaveTasks();
132
133  /**
134   * @return root node of simplified topology representation
135   */
136  TopologySimpleNode getTopologySimpleNodeRoot();
137
138  /**
139   * Asks the driver to update the topology of this communication group. This can
140   * be an expensive call depending on what the minimum number of tasks is for this
141   * group to function as this first tells the driver, driver then tells the affected
142   * tasks and the driver gives a green only after affected tasks have had a chance
143   * to be sure that their topology will be updated before the next message is
144   * communicated
145   */
146  void updateTopology();
147
148
149}