001    /* PipedReader.java -- Read portion of piped character streams.
002       Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010     
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package java.io;
039    
040    // NOTE: This implementation is very similar to that of PipedInputStream. 
041    // If you fix a bug in here, chances are you should make a similar change to 
042    // the PipedInputStream code.
043    
044    /**
045      * An input stream that reads characters from a piped writer to which it is 
046      * connected. 
047      * <p>
048      * Data is read and written to an internal buffer.  It is highly recommended
049      * that the <code>PipedReader</code> and connected <code>PipedWriter</code>
050      * be part of different threads.  If they are not, there is a possibility
051      * that the read and write operations could deadlock their thread.
052      *
053      * @specnote The JDK implementation appears to have some undocumented 
054      *           functionality where it keeps track of what thread is writing
055      *           to pipe and throws an IOException if that thread susequently
056      *           dies. This behaviour seems dubious and unreliable - we don't
057      *           implement it.
058      *
059      * @author Aaron M. Renn (arenn@urbanophile.com)
060      */
061    public class PipedReader extends Reader
062    {
063      /** PipedWriter to which this is connected. Null only if this 
064        * Reader hasn't been connected yet. */
065      PipedWriter source;
066    
067      /** Set to true if close() has been called on this Reader. */
068      boolean closed;
069    
070      /**
071        * The size of the internal buffer used for input/output.
072        */
073      static final int PIPE_SIZE = 2048;
074    
075      /**
076        * This is the internal circular buffer used for storing chars written
077        * to the pipe and from which chars are read by this stream
078        */
079      char[] buffer = new char[PIPE_SIZE];
080    
081      /**
082        * The index into buffer where the next char from the connected
083        * <code>PipedWriter</code> will be written. If this variable is 
084        * equal to <code>out</code>, then the buffer is full. If set to < 0,
085        * the buffer is empty.
086        */
087      int in = -1;
088    
089      /**
090        * This index into the buffer where chars will be read from.
091        */
092      int out = 0;
093    
094      /** Buffer used to implement single-argument read/receive */
095      char[] read_buf = new char[1];
096    
097      /**
098        * Creates a new <code>PipedReader</code> that is not connected to a 
099        * <code>PipedWriter</code>.  It must be connected before chars can 
100        * be read from this stream.
101        */
102      public PipedReader()
103      {
104      }
105    
106      /**
107        * This constructor creates a new <code>PipedReader</code> and connects
108        * it to the passed in <code>PipedWriter</code>. The stream is then 
109        * ready for reading.
110        *
111        * @param source The <code>PipedWriter</code> to connect this stream to
112        *
113        * @exception IOException If <code>source</code> is already connected.
114        */
115      public PipedReader(PipedWriter source) throws IOException
116      {
117        connect(source);
118      }
119    
120      /**
121        * This method connects this stream to the passed in 
122        * <code>PipedWriter</code>.
123        * This stream is then ready for reading.  If this stream is already
124        * connected or has been previously closed, then an exception is thrown
125        *
126        * @param source The <code>PipedWriter</code> to connect this stream to
127        *
128        * @exception IOException If this PipedReader or <code>source</code> 
129        *                        has been connected already.
130        */
131      public void connect(PipedWriter source) throws IOException
132      {
133        // The JDK (1.3) does not appear to check for a previously closed 
134        // connection here.
135        
136        if (this.source != null || source.sink != null)
137          throw new IOException ("Already connected");
138        
139        source.sink = this;
140        this.source = source;
141      }
142      
143      /**
144        * This method is used by the connected <code>PipedWriter</code> to
145        * write chars into the buffer.
146        *
147        * @param buf The array containing chars to write to this stream
148        * @param offset The offset into the array to start writing from
149        * @param len The number of chars to write.
150        *
151        * @exception IOException If an error occurs
152        * @specnote This code should be in PipedWriter.write, but we
153        *           put it here in order to support that bizarre recieve(int)
154        *           method.
155        */  
156      void receive(char[] buf, int offset, int len)
157        throws IOException
158      {
159        synchronized (lock)
160        {
161          if (closed)
162            throw new IOException ("Pipe closed");
163    
164          int bufpos = offset;
165          int copylen;
166    
167          while (len > 0)
168            {
169              try
170                {
171                  while (in == out)
172                    {
173                      // The pipe is full. Wake up any readers and wait for them.
174                      lock.notifyAll();
175                      lock.wait();
176                      // The pipe could have been closed while we were waiting.
177                      if (closed)
178                        throw new IOException ("Pipe closed");
179                    }
180                }
181              catch (InterruptedException ix)
182                {
183                  throw new InterruptedIOException ();
184                }
185    
186              if (in < 0) // The pipe is empty.
187                in = 0;
188    
189              // Figure out how many chars from buf can be copied without 
190              // overrunning out or going past the length of the buffer.
191              if (in < out)
192                copylen = Math.min (len, out - in);
193              else
194                copylen = Math.min (len, buffer.length - in);
195    
196              // Copy chars until the pipe is filled, wrapping if necessary.
197              System.arraycopy(buf, bufpos, buffer, in, copylen);
198              len -= copylen;
199              bufpos += copylen;
200              in += copylen;
201              if (in == buffer.length)
202                in = 0;
203            }
204          // Notify readers that new data is in the pipe.
205          lock.notifyAll();
206        }
207      }
208      
209      /**
210        * This method reads chars from the stream into a caller supplied buffer.
211        * It starts storing chars at position <code>offset</code> into the 
212        * buffer and
213        * reads a maximum of <code>len</code> chars.  Note that this method 
214        * can actually
215        * read fewer than <code>len</code> chars.  The actual number of chars 
216        * read is
217        * returned.  A -1 is returned to indicated that no chars can be read
218        * because the end of the stream was reached.  If the stream is already
219        * closed, a -1 will again be returned to indicate the end of the stream.
220        * <p>
221        * This method will block if no char is available to be read.
222        */
223      public int read() throws IOException
224      {
225        // Method operates by calling the multichar overloaded read method
226        // Note that read_buf is an internal instance variable.  I allocate it
227        // there to avoid constant reallocation overhead for applications that
228        // call this method in a loop at the cost of some unneeded overhead
229        // if this method is never called.
230    
231        int r = read(read_buf, 0, 1);
232        return r != -1 ? read_buf[0] : -1;
233      }
234      
235      /**
236        * This method reads characters from the stream into a caller supplied 
237        * buffer. It starts storing chars at position <code>offset</code> into 
238        * the buffer and reads a maximum of <code>len</code> chars.  Note that 
239        * this method can actually read fewer than <code>len</code> chars.  
240        * The actual number of chars read is
241        * returned.  A -1 is returned to indicated that no chars can be read
242        * because the end of the stream was reached - ie close() was called on the
243        * connected PipedWriter.
244        * <p>
245        * This method will block if no chars are available to be read.
246        *
247        * @param buf The buffer into which chars will be stored
248        * @param offset The index into the buffer at which to start writing.
249        * @param len The maximum number of chars to read.
250        *
251        * @exception IOException If <code>close()</code> was called on this Piped
252        *                        Reader.
253        */  
254      public int read(char[] buf, int offset, int len)
255        throws IOException
256      {
257        synchronized (lock)
258        {
259          if (source == null)
260            throw new IOException ("Not connected");
261          if (closed)
262            throw new IOException ("Pipe closed");
263    
264          // Don't block if nothing was requested.
265          if (len == 0)
266            return 0;
267    
268          // If the buffer is empty, wait until there is something in the pipe 
269          // to read.
270          try
271            {
272              while (in < 0)
273                {
274                  if (source.closed)
275                    return -1;
276                  lock.wait();
277                }
278            }
279          catch (InterruptedException ix)
280            {
281              throw new InterruptedIOException();
282            }
283    
284          int total = 0;
285          int copylen;
286    
287          while (true)
288            {
289              // Figure out how many chars from the pipe can be copied without 
290              // overrunning in or going past the length of buf.
291              if (out < in)
292                copylen = Math.min (len, in - out);
293              else
294                copylen = Math.min (len, buffer.length - out);
295    
296              System.arraycopy (buffer, out, buf, offset, copylen);
297              offset += copylen;
298              len -= copylen;
299              out += copylen;
300              total += copylen;
301    
302              if (out == buffer.length)
303                out = 0;
304    
305              if (out == in)
306                {
307                  // Pipe is now empty.
308                  in = -1;
309                  out = 0;
310                }
311    
312              // If output buffer is filled or the pipe is empty, we're done.
313              if (len == 0 || in == -1)
314                {
315                  // Notify any waiting Writer that there is now space
316                  // to write.
317                  lock.notifyAll();
318                  return total;
319                }
320            }
321        }
322      }
323      
324      public boolean ready() throws IOException
325      {
326        // The JDK 1.3 implementation does not appear to check for the closed or 
327        // unconnected stream conditions here.  However, checking for a
328        // closed stream is explicitly required by the JDK 1.2 and 1.3
329        // documentation (for Reader.close()), so we do it.
330        
331        synchronized (lock)
332        {
333          if (closed)
334            throw new IOException("Pipe closed");
335    
336          if (in < 0)
337            return false;
338    
339          int count;
340          if (out < in)
341            count = in - out;
342          else
343            count = (buffer.length - out) - in;
344    
345          return (count > 0);
346        }
347      }
348      
349      /**
350      * This methods closes the stream so that no more data can be read
351      * from it.
352      *
353      * @exception IOException If an error occurs
354      */
355      public void close() throws IOException
356      {
357        synchronized (lock)
358        {
359          closed = true;
360          // Wake any thread which may be in receive() waiting to write data.
361          lock.notifyAll();
362        }
363      }
364    }
365