View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.apache.giraph.comm.messages;
20  
21  import java.io.DataInput;
22  import java.io.DataOutput;
23  import java.io.IOException;
24  import org.apache.giraph.utils.VertexIdMessages;
25  import org.apache.hadoop.io.Writable;
26  import org.apache.hadoop.io.WritableComparable;
27  
28  /**
29   * Message store
30   *
31   * @param <I> Vertex id
32   * @param <M> Message data
33   */
34  public interface MessageStore<I extends WritableComparable,
35      M extends Writable> {
36    /**
37     * True if this message-store encodes messages as a list of long pointers
38     * to compact serialized messages
39     *
40     * @return true if we encode messages as a list of pointers
41     */
42    boolean isPointerListEncoding();
43  
44    /**
45     * Gets messages for a vertex.  The lifetime of every message is only
46     * guaranteed until the iterator's next() method is called. Do not hold
47     * references to objects returned by this iterator.
48     *
49     * @param vertexId Vertex id for which we want to get messages
50     * @return Iterable of messages for a vertex id
51     */
52    Iterable<M> getVertexMessages(I vertexId);
53  
54    /**
55     * Clears messages for a vertex.
56     *
57     * @param vertexId Vertex id for which we want to clear messages
58     */
59    void clearVertexMessages(I vertexId);
60  
61    /**
62     * Clears all resources used by this store.
63     */
64    void clearAll();
65  
66    /**
67     * Check if we have messages for some vertex
68     *
69     * @param vertexId Id of vertex which we want to check
70     * @return True iff we have messages for vertex with required id
71     */
72    boolean hasMessagesForVertex(I vertexId);
73  
74    /**
75     * Check if we have messages for some partition
76     *
77     * @param partitionId Id of partition which we want to check
78     * @return True iff we have messages for the given partition
79     */
80    boolean hasMessagesForPartition(int partitionId);
81  
82    /**
83     * Adds messages for partition
84     *
85     * @param partitionId Id of partition
86     * @param messages    Collection of vertex ids and messages we want to add
87     */
88    void addPartitionMessages(
89        int partitionId, VertexIdMessages<I, M> messages);
90  
91    /**
92     * Called before start of computation in bspworker
93     * Since it is run from a single thread while the store is not being
94     * accessed by any other thread - this is ensured to be thread-safe
95     */
96    void finalizeStore();
97  
98    /**
99     * Gets vertex ids from selected partition which we have messages for
100    *
101    * @param partitionId Id of partition
102    * @return Iterable over vertex ids which we have messages for
103    */
104   Iterable<I> getPartitionDestinationVertices(int partitionId);
105 
106   /**
107    * Clears messages for a partition.
108    *
109    * @param partitionId Partition id for which we want to clear messages
110    */
111   void clearPartition(int partitionId);
112 
113   /**
114    * Serialize messages for one partition.
115    *
116    * @param out         {@link DataOutput} to serialize this object into
117    * @param partitionId Id of partition
118    * @throws IOException
119    */
120   void writePartition(DataOutput out, int partitionId) throws IOException;
121 
122   /**
123    * Deserialize messages for one partition
124    *
125    * @param in          {@link DataInput} to deserialize this object
126    *                    from.
127    * @param partitionId Id of partition
128    * @throws IOException
129    */
130   void readFieldsForPartition(DataInput in,
131       int partitionId) throws IOException;
132 }