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}