/*
    * Licensed to the Apache Software Foundation (ASF) under one
    * or more contributor license agreements.  See the NOTICE file
    * distributed with this work for additional information
    * regarding copyright ownership.  The ASF licenses this file
    * to you under the Apache License, Version 2.0 (the
    * "License"); you may not use this file except in compliance
    * with the License.  You may obtain a copy of the License at
    *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.giraph.graph;
  
  import java.io.IOException;
  import java.util.Iterator;
  
  import org.apache.giraph.bsp.CentralizedServiceWorker;
  import org.apache.giraph.comm.WorkerClientRequestProcessor;
  import org.apache.giraph.conf.ImmutableClassesGiraphConfigurable;
  import org.apache.giraph.conf.TypesHolder;
  import org.apache.giraph.edge.Edge;
  import org.apache.giraph.edge.OutEdges;
  import org.apache.giraph.worker.WorkerAggregatorUsage;
  import org.apache.giraph.worker.WorkerContext;
  import org.apache.giraph.worker.WorkerGlobalCommUsage;
  import org.apache.giraph.worker.WorkerIndexUsage;
  import org.apache.hadoop.io.Writable;
  import org.apache.hadoop.io.WritableComparable;
  import org.apache.hadoop.mapreduce.Mapper;
  
  /**
   * Interface for an application for computation.
   *
   * During the superstep there can be several instances of this interface,
   * each doing computation on one partition of the graph's vertices.
   *
   * Note that each thread will have its own {@link Computation},
   * so accessing any data from this class is thread-safe.
   * However, accessing global data (like data from {@link WorkerContext})
   * is not thread-safe.
   *
   * Objects of this interface only live for a single superstep.
   *
   * @param <I> Vertex id
   * @param <V> Vertex data
   * @param <E> Edge data
   * @param <M1> Incoming message type
   * @param <M2> Outgoing message type
   */
  public interface Computation<I extends WritableComparable,
      V extends Writable, E extends Writable, M1 extends Writable,
      M2 extends Writable>
      extends TypesHolder<I, V, E, M1, M2>,
      ImmutableClassesGiraphConfigurable<I, V, E>,
      WorkerGlobalCommUsage, WorkerAggregatorUsage, WorkerIndexUsage<I> {
    /**
     * Must be defined by user to do computation on a single Vertex.
     *
     * @param vertex   Vertex
     * @param messages Messages that were sent to this vertex in the previous
     *                 superstep.  Each message is only guaranteed to have
     *                 a life expectancy as long as next() is not called.
     */
    void compute(Vertex<I, V, E> vertex, Iterable<M1> messages)
      throws IOException;
  
    /**
     * Prepare for computation. This method is executed exactly once prior to
     * {@link #compute(Vertex, Iterable)} being called for any of the vertices
     * in the partition.
     */
    void preSuperstep();
  
    /**
     * Finish computation. This method is executed exactly once after computation
     * for all vertices in the partition is complete.
     */
    void postSuperstep();
  
    /**
     * Initialize, called by infrastructure before the superstep starts.
     * Shouldn't be called by user code.
     *
     * @param graphState Graph state
     * @param workerClientRequestProcessor Processor for handling requests
     * @param serviceWorker Centralized service worker
     * @param workerGlobalCommUsage Worker global communication usage
     */
    void initialize(GraphState graphState,
        WorkerClientRequestProcessor<I, V, E> workerClientRequestProcessor,
        CentralizedServiceWorker<I, V, E> serviceWorker,
        WorkerGlobalCommUsage workerGlobalCommUsage);
  
   /**
    * Retrieves the current superstep.
    *
    * @return Current superstep
    */
   long getSuperstep();
 
   /**
    * Get the total (all workers) number of vertices that
    * existed in the previous superstep.
    *
    * @return Total number of vertices (-1 if first superstep)
    */
   long getTotalNumVertices();
 
   /**
    * Get the total (all workers) number of edges that
    * existed in the previous superstep.
    *
    * @return Total number of edges (-1 if first superstep)
    */
   long getTotalNumEdges();
 
   /**
    * Send a message to a vertex id.
    *
    * @param id Vertex id to send the message to
    * @param message Message data to send
    */
   void sendMessage(I id, M2 message);
 
   /**
    * Send a message to all edges.
    *
    * @param vertex Vertex whose edges to send the message to.
    * @param message Message sent to all edges.
    */
   void sendMessageToAllEdges(Vertex<I, V, E> vertex, M2 message);
 
   /**
    * Send a message to multiple target vertex ids in the iterator.
    *
    * @param vertexIdIterator An iterator to multiple target vertex ids.
    * @param message Message sent to all targets in the iterator.
    */
   void sendMessageToMultipleEdges(Iterator<I> vertexIdIterator, M2 message);
 
   /**
    * Sends a request to create a vertex that will be available during the
    * next superstep.
    *
    * @param id Vertex id
    * @param value Vertex value
    * @param edges Initial edges
    * @throws IOException
    */
   void addVertexRequest(I id, V value, OutEdges<I, E> edges) throws IOException;
 
   /**
    * Sends a request to create a vertex that will be available during the
    * next superstep.
    *
    * @param id Vertex id
    * @param value Vertex value
    * @throws IOException
    */
   void addVertexRequest(I id, V value) throws IOException;
 
   /**
    * Request to remove a vertex from the graph
    * (applied just prior to the next superstep).
    *
    * @param vertexId Id of the vertex to be removed.
    * @throws IOException
    */
   void removeVertexRequest(I vertexId) throws IOException;
 
   /**
    * Request to add an edge of a vertex in the graph
    * (processed just prior to the next superstep)
    *
    * @param sourceVertexId Source vertex id of edge
    * @param edge Edge to add
    * @throws IOException
    */
   void addEdgeRequest(I sourceVertexId, Edge<I, E> edge) throws IOException;
 
   /**
    * Request to remove all edges from a given source vertex to a given target
    * vertex (processed just prior to the next superstep).
    *
    * @param sourceVertexId Source vertex id
    * @param targetVertexId Target vertex id
    * @throws IOException
    */
   void removeEdgesRequest(I sourceVertexId, I targetVertexId)
     throws IOException;
 
   /**
    * Get the mapper context
    *
    * @return Mapper context
    */
   Mapper.Context getContext();
 
   /**
    * Get the worker context
    *
    * @param <W> WorkerContext class
    * @return WorkerContext context
    */
   @SuppressWarnings("unchecked")
   <W extends WorkerContext> W getWorkerContext();
 }