| /* |
| * 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(); |
| } |