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.driver;
020
021import org.apache.reef.annotations.audience.DriverSide;
022import org.apache.reef.io.network.group.impl.config.BroadcastOperatorSpec;
023import org.apache.reef.io.network.group.impl.config.GatherOperatorSpec;
024import org.apache.reef.io.network.group.impl.config.ReduceOperatorSpec;
025import org.apache.reef.io.network.group.impl.config.ScatterOperatorSpec;
026import org.apache.reef.io.network.group.impl.driver.CommunicationGroupDriverImpl;
027import org.apache.reef.tang.Configuration;
028import org.apache.reef.tang.annotations.DefaultImplementation;
029import org.apache.reef.tang.annotations.Name;
030
031/**
032 * The driver side interface of a Communication Group
033 * Lets one add operators and tasks.
034 * Main function is to extract the configuration related
035 * to the Group Communication for a task in the comm group
036 */
037@DriverSide
038@DefaultImplementation(CommunicationGroupDriverImpl.class)
039public interface CommunicationGroupDriver {
040
041  /**
042   * Add the broadcast operator specified by the.
043   * 'spec' with name 'operatorName' into this
044   * Communication Group
045   *
046   * @param operatorName
047   * @param spec
048   * @return
049   */
050  CommunicationGroupDriver addBroadcast(Class<? extends Name<String>> operatorName, BroadcastOperatorSpec spec);
051
052  /**
053   * Add the reduce operator specified by the.
054   * 'spec' with name 'operatorName' into this
055   * Communication Group
056   *
057   * @param operatorName
058   * @param spec
059   * @return
060   */
061  CommunicationGroupDriver addReduce(Class<? extends Name<String>> operatorName, ReduceOperatorSpec spec);
062
063  /**
064   * Add the scatter operator specified by {@code operatorName} and {@code spec}.
065   *
066   * @param operatorName
067   * @param spec
068   * @return
069   */
070  CommunicationGroupDriver addScatter(Class<? extends Name<String>> operatorName, ScatterOperatorSpec spec);
071
072  /**
073   * Add the gather operator specified by {@code operatorName} and {@code spec}.
074   *
075   * @param operatorName
076   * @param spec
077   * @return
078   */
079  CommunicationGroupDriver addGather(Class<? extends Name<String>> operatorName, GatherOperatorSpec spec);
080
081  /**
082   * This signals to the service that no more.
083   * operator specs will be added to this communication
084   * group and an attempt to do that will throw an
085   * IllegalStateException
086   */
087  void finalise();
088
089  /**
090   * Returns a configuration that includes the partial task
091   * configuration passed in as 'taskConf' and makes the
092   * current communication group and the operators configured
093   * on it available on the Task side. Provides for injection
094   * of {@link org.apache.reef.io.network.group.api.task.GroupCommClient}
095   *
096   * @param taskConf
097   * @return
098   */
099  Configuration getTaskConfiguration(Configuration taskConf);
100
101  /**
102   * Add the task represented by this configuration to this
103   * communication group. The configuration needs to contain
104   * the id of the Task that will be used
105   *
106   * @param partialTaskConf
107   */
108  void addTask(Configuration partialTaskConf);
109}