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.flow_control;
20  
21  import org.apache.giraph.comm.netty.handler.AckSignalFlag;
22  import org.apache.giraph.comm.requests.WritableRequest;
23  
24  /**
25   * Interface representing flow control policy in sending requests
26   */
27  public interface FlowControl {
28    /**
29     * This method is called by a network client for all requests that should be
30     * handled by a *remote* task. All these requests should be controlled and/or
31     * monitored by the flow control policy. The flow control policy may choose to
32     * temporarily hold off from sending to a particular remote task and keep the
33     * request in some cache for later transfer. A flow control mechanism is free
34     * to implement this method as blocking or non-blocking. Note that, a
35     * flow-control policy should adhere to exactly-once semantic, meaning it
36     * should always send one and only one copy of each request that should be
37     * handled by a remote task.
38     *
39     * @param destTaskId id of the worker to send the request to
40     * @param request request to send
41     */
42    void sendRequest(int destTaskId, WritableRequest request);
43  
44    /**
45     * Notify the flow control policy that an open request is completed.
46     *
47     * @param taskId id of the task to which the open request is completed
48     * @param requestId id of the open request which is completed
49     * @param response the response heard from the client
50     */
51    void messageAckReceived(int taskId, long requestId, int response);
52  
53    /**
54     * Decode the acknowledgement signal from the response after an open request
55     * is completed
56     *
57     * @param response the response heard after completion of a request
58     * @return the Acknowledgement signal decoded from the response
59     */
60    AckSignalFlag getAckSignalFlag(int response);
61  
62    /**
63     * There may be requests in possession of the flow control mechanism, as the
64     * mechanism controls whether a task should send a request or not.
65     * Calling this method causes the caller to wait until all requests in
66     * possession of the flow control mechanism are sent out.
67     */
68    void waitAllRequests();
69  
70    /**
71     * @return number of unsent requests in possession of the flow control policy
72     */
73    int getNumberOfUnsentRequests();
74  
75    /**
76     * Calculate/Build the response to piggyback with acknowledgement
77     *
78     * @param flag indicating the status of processing of the request (whether it
79     *             was a new request or it was a duplicate)
80     * @param taskId id of the task the acknowledgement is for
81     * @return the response to piggyback along with the acknowledgement message
82     */
83    int calculateResponse(AckSignalFlag flag, int taskId);
84  
85    /**
86     * Shutdown the flow control policy
87     */
88    void shutdown();
89  
90    /**
91     * Log the status of the flow control
92     */
93    void logInfo();
94  }