001/*
002 * Copyright 2006 - 2013
003 *     Stefan Balev     <stefan.balev@graphstream-project.org>
004 *     Julien Baudry    <julien.baudry@graphstream-project.org>
005 *     Antoine Dutot    <antoine.dutot@graphstream-project.org>
006 *     Yoann Pigné      <yoann.pigne@graphstream-project.org>
007 *     Guilhelm Savin   <guilhelm.savin@graphstream-project.org>
008 * 
009 * This file is part of GraphStream <http://graphstream-project.org>.
010 * 
011 * GraphStream is a library whose purpose is to handle static or dynamic
012 * graph, create them from scratch, file or any source and display them.
013 * 
014 * This program is free software distributed under the terms of two licenses, the
015 * CeCILL-C license that fits European law, and the GNU Lesser General Public
016 * License. You can  use, modify and/ or redistribute the software under the terms
017 * of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following
018 * URL <http://www.cecill.info> or under the terms of the GNU LGPL as published by
019 * the Free Software Foundation, either version 3 of the License, or (at your
020 * option) any later version.
021 * 
022 * This program is distributed in the hope that it will be useful, but WITHOUT ANY
023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
024 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
025 * 
026 * You should have received a copy of the GNU Lesser General Public License
027 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
028 * 
029 * The fact that you are presently reading this means that you have had
030 * knowledge of the CeCILL-C and LGPL licenses and that you accept their terms.
031 */
032package org.graphstream.stream;
033
034/**
035 * Proxy pipe.
036 * 
037 * <p>
038 * A proxy is a kind of event buffer that allows to pass some kind of barrier.
039 * The barrier can be a thread or a network for example. A proxy completely
040 * decouple the source from the sink. The proxy buffers the source events and
041 * when possible it sends them to the listeners at the sink. In other words, a
042 * proxy is indirect, non synchronized and non blocking.
043 * </p>
044 * 
045 * <p>
046 * The usual source/sink mechanism is synchronized, direct and blocking : when
047 * the event occurs, all listeners are called, and we have to wait they finish
048 * to process these events to continue and send new events.
049 * </p>
050 * 
051 * <p>
052 * With proxies, there is a buffer often compared to a mail box. Each event
053 * produced as source is buffered and when the sink is free to receive these
054 * events it can check the mail box and empty it, thus receiving the pending
055 * events. This way of doing is completely non synchronized and non blocking
056 * (due to the mail box).
057 * </p>
058 * 
059 * <p>
060 * This way of doing allows for example to pass a thread frontier with a minimum
061 * of synchronization : only the mail box has to be synchronized. And the source
062 * and sink can most of the time run in parallel. Without such a proxy, we would
063 * have to synchronize the whole graph, and threads would consume their time
064 * waiting one another since most of the work in GraphStream is centered on
065 * graphs.
066 * </p>
067 * 
068 * <p>
069 * For networks, this is the same thing : events are buffered before sending
070 * them to the network. When the other end is ready it can check these events in
071 * one operation.
072 * </p>
073 * 
074 * <p>
075 * However proxies have a limitation : they force the receiving end to check for
076 * events regularly. This can be compared to "pumping" since the whole
077 * GraphStream metaphor is a set of sources, pipes and sinks. Here instead of
078 * flowing freely, the event stream must be pumped manually to receive it. This
079 * is however most of the time not a problem since most work on graphs in
080 * GraphStream is dynamic and runs iteratively.
081 * </p>
082 */
083public interface ProxyPipe extends Pipe {
084        /**
085         * Check if some events are pending and dispatch them to the registered
086         * outputs.
087         */
088        void pump();
089
090        /**
091         * Same as {@link #pump()} but try to block until new events were available.
092         * Note that this feature will not be available on all proxy pipe
093         * implementation and may throws an
094         * {@link java.lang.UnsupportedOperationException}. It can throw an
095         * {@link java.lang.InterruptedException} if the current thread is
096         * interrupted while proxy is waiting for events.
097         */
098        void blockingPump() throws InterruptedException;
099
100        /**
101         * Same as {@link #blockingPump()} but including a timeout delay.
102         * 
103         * @param timeout
104         * @throws InterruptedException
105         */
106        void blockingPump(long timeout) throws InterruptedException;
107}