package anastore.net;

import anastore.util.*;
import java.io.IOException;

/**
 * Receive half of a channel. Receives message from the network.
 */
public interface ReceiveChannel {

    /**
     * Receive a message. Blocks until a message is available, or
     * interrupted.
     *
     * @returns the Message and a SendChannel for sending
     * replies. The SendChannel may be null if the message is
     * asynchronous, or the behavior of the channel may be
     * unspecified.
     *
     * @throws IOException if a network error occurred
     * @throws InterruptedException if the thread was interrupted
     * while blocking for input.
     */
    public Pair<Message, SendChannel> receive()
        throws ChannelClosedException, InterruptedException;

    /**
     * Receive an asynchronous message.  This is a convenience wrapper
     * for {@link #receive()} that essentially discards the channel.
     *
     * @throws IOException if a network error occurred
     * @throws InterruptedException if the thread was interrupted
     * while blocking for input.
     * @throws IllegalStateException if the received message is
     * synchronous
     */
    public AsyncMessage receiveAsync()
        throws ChannelClosedException, InterruptedException,
               IllegalStateException;
}