src/libstd/io/pipe.rs

   1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Synchronous, in-memory pipes.
  12 //!
  13 //! Currently these aren't particularly useful, there only exists bindings
  14 //! enough so that pipes can be created to child processes.
  15
  16 #![allow(missing_doc)]
  17
  18 use prelude::*;
  19 use io::IoResult;
  20 use libc;
  21 use rt::rtio::{RtioPipe, LocalIo};
  22
  23 /// A synchronous, in-memory pipe.
  24 pub struct PipeStream {
  25     /// The internal, opaque runtime pipe object.
  26     obj: ~RtioPipe:Send,
  27 }
  28
  29 impl PipeStream {
  30     /// Consumes a file descriptor to return a pipe stream that will have
  31     /// synchronous, but non-blocking reads/writes. This is useful if the file
  32     /// descriptor is acquired via means other than the standard methods.
  33     ///
  34     /// This operation consumes ownership of the file descriptor and it will be
  35     /// closed once the object is deallocated.
  36     ///
  37     /// # Example
  38     ///
  39     /// ```rust
  40     /// # #![allow(unused_must_use)]
  41     /// extern crate libc;
  42     ///
  43     /// use std::io::pipe::PipeStream;
  44     ///
  45     /// fn main() {
  46     ///     let mut pipe = PipeStream::open(libc::STDERR_FILENO);
  47     ///     pipe.write(bytes!("Hello, stderr!"));
  48     /// }
  49     /// ```
  50     pub fn open(fd: libc::c_int) -> IoResult<PipeStream> {
  51         LocalIo::maybe_raise(|io| {
  52             io.pipe_open(fd).map(|obj| PipeStream { obj: obj })
  53         })
  54     }
  55
  56     #[doc(hidden)]
  57     pub fn new(inner: ~RtioPipe:Send) -> PipeStream {
  58         PipeStream { obj: inner }
  59     }
  60 }
  61
  62 impl Clone for PipeStream {
  63     fn clone(&self) -> PipeStream {
  64         PipeStream { obj: self.obj.clone() }
  65     }
  66 }
  67
  68 impl Reader for PipeStream {
  69     fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { self.obj.read(buf) }
  70 }
  71
  72 impl Writer for PipeStream {
  73     fn write(&mut self, buf: &[u8]) -> IoResult<()> { self.obj.write(buf) }
  74 }
  75
  76 #[cfg(test)]
  77 mod test {
  78     iotest!(fn partial_read() {
  79         use os;
  80         use io::pipe::PipeStream;
  81
  82         let os::Pipe { input, out } = os::pipe();
  83         let out = PipeStream::open(out);
  84         let mut input = PipeStream::open(input);
  85         let (tx, rx) = channel();
  86         spawn(proc() {
  87             let mut out = out;
  88             out.write([10]).unwrap();
  89             rx.recv(); // don't close the pipe until the other read has finished
  90         });
  91
  92         let mut buf = [0, ..10];
  93         input.read(buf).unwrap();
  94         tx.send(());
  95     })
  96 }