user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

/*! -> //!

Browse source 
Sister pull request of https://github.com/rust-lang/rust/pull/19288, but
for the other style of block doc comment.
This commit is contained in:
Steve Klabnik 2014-11-25 21:17:11 -05:00 • committed by Alex Crichton
parent fac5a07679
commit cd5c8235c5
119 changed files with 6859 additions and 8079 deletions
Download patch file Download diff file Expand all files Collapse all files

80
src/libstd/io/fs.rs
View file

@ -10,47 +10,45 @@
//
// ignore-lexer-test FIXME #15679
/*! Synchronous File I/O
This module provides a set of functions and traits for working
with regular files & directories on a filesystem.
At the top-level of the module are a set of freestanding functions, associated
with various filesystem operations. They all operate on `Path` objects.
All operations in this module, including those as part of `File` et al
block the task during execution. In the event of failure, all functions/methods
will return an `IoResult` type with an `Err` value.
Also included in this module is an implementation block on the `Path` object
defined in `std::path::Path`. The impl adds useful methods about inspecting the
metadata of a file. This includes getting the `stat` information, reading off
particular bits of it, etc.
# Example
```rust
# #![allow(unused_must_use)]
use std::io::fs::PathExtensions;
use std::io::{File, fs};
let path = Path::new("foo.txt");
// create the file, whether it exists or not
let mut file = File::create(&path);
file.write(b"foobar");
# drop(file);
// open the file in read-only mode
let mut file = File::open(&path);
file.read_to_end();
println!("{}", path.stat().unwrap().size);
# drop(file);
fs::unlink(&path);
```
*/
//! Synchronous File I/O
//!
//! This module provides a set of functions and traits for working
//! with regular files & directories on a filesystem.
//!
//! At the top-level of the module are a set of freestanding functions, associated
//! with various filesystem operations. They all operate on `Path` objects.
//!
//! All operations in this module, including those as part of `File` et al
//! block the task during execution. In the event of failure, all functions/methods
//! will return an `IoResult` type with an `Err` value.
//!
//! Also included in this module is an implementation block on the `Path` object
//! defined in `std::path::Path`. The impl adds useful methods about inspecting the
//! metadata of a file. This includes getting the `stat` information, reading off
//! particular bits of it, etc.
//!
//! # Example
//!
//! ```rust
//! # #![allow(unused_must_use)]
//! use std::io::fs::PathExtensions;
//! use std::io::{File, fs};
//!
//! let path = Path::new("foo.txt");
//!
//! // create the file, whether it exists or not
//! let mut file = File::create(&path);
//! file.write(b"foobar");
//! # drop(file);
//!
//! // open the file in read-only mode
//! let mut file = File::open(&path);
//! file.read_to_end();
//!
//! println!("{}", path.stat().unwrap().size);
//! # drop(file);
//! fs::unlink(&path);
//! ```
use clone::Clone;
use io::standard_error;

400
src/libstd/io/mod.rs
View file

@ -16,207 +16,205 @@
// error handling
/*! I/O, including files, networking, timers, and processes
`std::io` provides Rust's basic I/O types,
for reading and writing to files, TCP, UDP,
and other types of sockets and pipes,
manipulating the file system, spawning processes.
# Examples
Some examples of obvious things you might want to do
* Read lines from stdin
```rust
use std::io;
for line in io::stdin().lines() {
print!("{}", line.unwrap());
}
```
* Read a complete file
```rust
use std::io::File;
let contents = File::open(&Path::new("message.txt")).read_to_end();
```
* Write a line to a file
```rust
# #![allow(unused_must_use)]
use std::io::File;
let mut file = File::create(&Path::new("message.txt"));
file.write(b"hello, file!\n");
# drop(file);
# ::std::io::fs::unlink(&Path::new("message.txt"));
```
* Iterate over the lines of a file
```rust,no_run
use std::io::BufferedReader;
use std::io::File;
let path = Path::new("message.txt");
let mut file = BufferedReader::new(File::open(&path));
for line in file.lines() {
print!("{}", line.unwrap());
}
```
* Pull the lines of a file into a vector of strings
```rust,no_run
use std::io::BufferedReader;
use std::io::File;
let path = Path::new("message.txt");
let mut file = BufferedReader::new(File::open(&path));
let lines: Vec<String> = file.lines().map(|x| x.unwrap()).collect();
```
* Make a simple TCP client connection and request
```rust
# #![allow(unused_must_use)]
use std::io::TcpStream;
# // connection doesn't fail if a server is running on 8080
# // locally, we still want to be type checking this code, so lets
# // just stop it running (#11576)
# if false {
let mut socket = TcpStream::connect("127.0.0.1:8080").unwrap();
socket.write(b"GET / HTTP/1.0\n\n");
let response = socket.read_to_end();
# }
```
* Make a simple TCP server
```rust
# fn main() { }
# fn foo() {
# #![allow(dead_code)]
use std::io::{TcpListener, TcpStream};
use std::io::{Acceptor, Listener};
let listener = TcpListener::bind("127.0.0.1:80");
// bind the listener to the specified address
let mut acceptor = listener.listen();
fn handle_client(mut stream: TcpStream) {
// ...
# &mut stream; // silence unused mutability/variable warning
}
// accept connections and process them, spawning a new tasks for each one
for stream in acceptor.incoming() {
match stream {
Err(e) => { /* connection failed */ }
Ok(stream) => spawn(proc() {
// connection succeeded
handle_client(stream)
})
}
}
// close the socket server
drop(acceptor);
# }
```
# Error Handling
I/O is an area where nearly every operation can result in unexpected
errors. Errors should be painfully visible when they happen, and handling them
should be easy to work with. It should be convenient to handle specific I/O
errors, and it should also be convenient to not deal with I/O errors.
Rust's I/O employs a combination of techniques to reduce boilerplate
while still providing feedback about errors. The basic strategy:
* All I/O operations return `IoResult<T>` which is equivalent to
`Result<T, IoError>`. The `Result` type is defined in the `std::result`
module.
* If the `Result` type goes unused, then the compiler will by default emit a
warning about the unused result. This is because `Result` has the
`#[must_use]` attribute.
* Common traits are implemented for `IoResult`, e.g.
`impl<R: Reader> Reader for IoResult<R>`, so that error values do not have
to be 'unwrapped' before use.
These features combine in the API to allow for expressions like
`File::create(&Path::new("diary.txt")).write(b"Met a girl.\n")`
without having to worry about whether "diary.txt" exists or whether
the write succeeds. As written, if either `new` or `write_line`
encounters an error then the result of the entire expression will
be an error.
If you wanted to handle the error though you might write:
```rust
# #![allow(unused_must_use)]
use std::io::File;
match File::create(&Path::new("diary.txt")).write(b"Met a girl.\n") {
Ok(()) => (), // succeeded
Err(e) => println!("failed to write to my diary: {}", e),
}
# ::std::io::fs::unlink(&Path::new("diary.txt"));
```
So what actually happens if `create` encounters an error?
It's important to know that what `new` returns is not a `File`
but an `IoResult<File>`. If the file does not open, then `new` will simply
return `Err(..)`. Because there is an implementation of `Writer` (the trait
required ultimately required for types to implement `write_line`) there is no
need to inspect or unwrap the `IoResult<File>` and we simply call `write_line`
on it. If `new` returned an `Err(..)` then the followup call to `write_line`
will also return an error.
## `try!`
Explicit pattern matching on `IoResult`s can get quite verbose, especially
when performing many I/O operations. Some examples (like those above) are
alleviated with extra methods implemented on `IoResult`, but others have more
complex interdependencies among each I/O operation.
The `try!` macro from `std::macros` is provided as a method of early-return
inside `Result`-returning functions. It expands to an early-return on `Err`
and otherwise unwraps the contained `Ok` value.
If you wanted to read several `u32`s from a file and return their product:
```rust
use std::io::{File, IoResult};
fn file_product(p: &Path) -> IoResult<u32> {
let mut f = File::open(p);
let x1 = try!(f.read_le_u32());
let x2 = try!(f.read_le_u32());
Ok(x1 * x2)
}
match file_product(&Path::new("numbers.bin")) {
Ok(x) => println!("{}", x),
Err(e) => println!("Failed to read numbers!")
}
```
With `try!` in `file_product`, each `read_le_u32` need not be directly
concerned with error handling; instead its caller is responsible for
responding to errors that may occur while attempting to read the numbers.
*/
//! I/O, including files, networking, timers, and processes
//!
//! `std::io` provides Rust's basic I/O types,
//! for reading and writing to files, TCP, UDP,
//! and other types of sockets and pipes,
//! manipulating the file system, spawning processes.
//!
//! # Examples
//!
//! Some examples of obvious things you might want to do
//!
//! * Read lines from stdin
//!
//! ```rust
//! use std::io;
//!
//! for line in io::stdin().lines() {
//! print!("{}", line.unwrap());
//! }
//! ```
//!
//! * Read a complete file
//!
//! ```rust
//! use std::io::File;
//!
//! let contents = File::open(&Path::new("message.txt")).read_to_end();
//! ```
//!
//! * Write a line to a file
//!
//! ```rust
//! # #![allow(unused_must_use)]
//! use std::io::File;
//!
//! let mut file = File::create(&Path::new("message.txt"));
//! file.write(b"hello, file!\n");
//! # drop(file);
//! # ::std::io::fs::unlink(&Path::new("message.txt"));
//! ```
//!
//! * Iterate over the lines of a file
//!
//! ```rust,no_run
//! use std::io::BufferedReader;
//! use std::io::File;
//!
//! let path = Path::new("message.txt");
//! let mut file = BufferedReader::new(File::open(&path));
//! for line in file.lines() {
//! print!("{}", line.unwrap());
//! }
//! ```
//!
//! * Pull the lines of a file into a vector of strings
//!
//! ```rust,no_run
//! use std::io::BufferedReader;
//! use std::io::File;
//!
//! let path = Path::new("message.txt");
//! let mut file = BufferedReader::new(File::open(&path));
//! let lines: Vec<String> = file.lines().map(|x| x.unwrap()).collect();
//! ```
//!
//! * Make a simple TCP client connection and request
//!
//! ```rust
//! # #![allow(unused_must_use)]
//! use std::io::TcpStream;
//!
//! # // connection doesn't fail if a server is running on 8080
//! # // locally, we still want to be type checking this code, so lets
//! # // just stop it running (#11576)
//! # if false {
//! let mut socket = TcpStream::connect("127.0.0.1:8080").unwrap();
//! socket.write(b"GET / HTTP/1.0\n\n");
//! let response = socket.read_to_end();
//! # }
//! ```
//!
//! * Make a simple TCP server
//!
//! ```rust
//! # fn main() { }
//! # fn foo() {
//! # #![allow(dead_code)]
//! use std::io::{TcpListener, TcpStream};
//! use std::io::{Acceptor, Listener};
//!
//! let listener = TcpListener::bind("127.0.0.1:80");
//!
//! // bind the listener to the specified address
//! let mut acceptor = listener.listen();
//!
//! fn handle_client(mut stream: TcpStream) {
//! // ...
//! # &mut stream; // silence unused mutability/variable warning
//! }
//! // accept connections and process them, spawning a new tasks for each one
//! for stream in acceptor.incoming() {
//! match stream {
//! Err(e) => { /* connection failed */ }
//! Ok(stream) => spawn(proc() {
//! // connection succeeded
//! handle_client(stream)
//! })
//! }
//! }
//!
//! // close the socket server
//! drop(acceptor);
//! # }
//! ```
//!
//!
//! # Error Handling
//!
//! I/O is an area where nearly every operation can result in unexpected
//! errors. Errors should be painfully visible when they happen, and handling them
//! should be easy to work with. It should be convenient to handle specific I/O
//! errors, and it should also be convenient to not deal with I/O errors.
//!
//! Rust's I/O employs a combination of techniques to reduce boilerplate
//! while still providing feedback about errors. The basic strategy:
//!
//! * All I/O operations return `IoResult<T>` which is equivalent to
//! `Result<T, IoError>`. The `Result` type is defined in the `std::result`
//! module.
//! * If the `Result` type goes unused, then the compiler will by default emit a
//! warning about the unused result. This is because `Result` has the
//! `#[must_use]` attribute.
//! * Common traits are implemented for `IoResult`, e.g.
//! `impl<R: Reader> Reader for IoResult<R>`, so that error values do not have
//! to be 'unwrapped' before use.
//!
//! These features combine in the API to allow for expressions like
//! `File::create(&Path::new("diary.txt")).write(b"Met a girl.\n")`
//! without having to worry about whether "diary.txt" exists or whether
//! the write succeeds. As written, if either `new` or `write_line`
//! encounters an error then the result of the entire expression will
//! be an error.
//!
//! If you wanted to handle the error though you might write:
//!
//! ```rust
//! # #![allow(unused_must_use)]
//! use std::io::File;
//!
//! match File::create(&Path::new("diary.txt")).write(b"Met a girl.\n") {
//! Ok(()) => (), // succeeded
//! Err(e) => println!("failed to write to my diary: {}", e),
//! }
//!
//! # ::std::io::fs::unlink(&Path::new("diary.txt"));
//! ```
//!
//! So what actually happens if `create` encounters an error?
//! It's important to know that what `new` returns is not a `File`
//! but an `IoResult<File>`. If the file does not open, then `new` will simply
//! return `Err(..)`. Because there is an implementation of `Writer` (the trait
//! required ultimately required for types to implement `write_line`) there is no
//! need to inspect or unwrap the `IoResult<File>` and we simply call `write_line`
//! on it. If `new` returned an `Err(..)` then the followup call to `write_line`
//! will also return an error.
//!
//! ## `try!`
//!
//! Explicit pattern matching on `IoResult`s can get quite verbose, especially
//! when performing many I/O operations. Some examples (like those above) are
//! alleviated with extra methods implemented on `IoResult`, but others have more
//! complex interdependencies among each I/O operation.
//!
//! The `try!` macro from `std::macros` is provided as a method of early-return
//! inside `Result`-returning functions. It expands to an early-return on `Err`
//! and otherwise unwraps the contained `Ok` value.
//!
//! If you wanted to read several `u32`s from a file and return their product:
//!
//! ```rust
//! use std::io::{File, IoResult};
//!
//! fn file_product(p: &Path) -> IoResult<u32> {
//! let mut f = File::open(p);
//! let x1 = try!(f.read_le_u32());
//! let x2 = try!(f.read_le_u32());
//!
//! Ok(x1 * x2)
//! }
//!
//! match file_product(&Path::new("numbers.bin")) {
//! Ok(x) => println!("{}", x),
//! Err(e) => println!("Failed to read numbers!")
//! }
//! ```
//!
//! With `try!` in `file_product`, each `read_le_u32` need not be directly
//! concerned with error handling; instead its caller is responsible for
//! responding to errors that may occur while attempting to read the numbers.
#![experimental]
#![deny(unused_must_use)]

12
src/libstd/io/net/addrinfo.rs
View file

@ -8,14 +8,10 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*!
Synchronous DNS Resolution
Contains the functionality to perform DNS resolution in a style related to
getaddrinfo()
*/
//! Synchronous DNS Resolution
//!
//! Contains the functionality to perform DNS resolution in a style related to
//! `getaddrinfo()`
#![allow(missing_docs)]

22
src/libstd/io/net/pipe.rs
View file

@ -8,19 +8,15 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*!
Named pipes
This module contains the ability to communicate over named pipes with
synchronous I/O. On windows, this corresponds to talking over a Named Pipe,
while on Unix it corresponds to UNIX domain sockets.
These pipes are similar to TCP in the sense that you can have both a stream to a
server and a server itself. The server provided accepts other `UnixStream`
instances as clients.
*/
//! Named pipes
//!
//! This module contains the ability to communicate over named pipes with
//! synchronous I/O. On windows, this corresponds to talking over a Named Pipe,
//! while on Unix it corresponds to UNIX domain sockets.
//!
//! These pipes are similar to TCP in the sense that you can have both a stream to a
//! server and a server itself. The server provided accepts other `UnixStream`
//! instances as clients.
#![allow(missing_docs)]

34
src/libstd/io/stdio.rs
View file

@ -8,24 +8,22 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*! Non-blocking access to stdin, stdout, and stderr.
This module provides bindings to the local event loop's TTY interface, using it
to offer synchronous but non-blocking versions of stdio. These handles can be
inspected for information about terminal dimensions or for related information
about the stream or terminal to which it is attached.
# Example
```rust
# #![allow(unused_must_use)]
use std::io;
let mut out = io::stdout();
out.write(b"Hello, world!");
```
*/
//! Non-blocking access to stdin, stdout, and stderr.
//!
//! This module provides bindings to the local event loop's TTY interface, using it
//! to offer synchronous but non-blocking versions of stdio. These handles can be
//! inspected for information about terminal dimensions or for related information
//! about the stream or terminal to which it is attached.
//!
//! # Example
//!
//! ```rust
//! # #![allow(unused_must_use)]
//! use std::io;
//!
//! let mut out = io::stdout();
//! out.write(b"Hello, world!");
//! ```
use self::StdSource::*;

15
src/libstd/io/test.rs
View file

@ -8,7 +8,7 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*! Various utility functions useful for writing I/O tests */
//! Various utility functions useful for writing I/O tests
#![macro_escape]
@ -95,17 +95,14 @@ pub fn raise_fd_limit() {
unsafe { darwin_fd_limit::raise_fd_limit() }
}
/// darwin_fd_limit exists to work around an issue where launchctl on Mac OS X defaults the rlimit
/// maxfiles to 256/unlimited. The default soft limit of 256 ends up being far too low for our
/// multithreaded scheduler testing, depending on the number of cores available.
///
/// This fixes issue #7772.
#[cfg(target_os="macos")]
#[allow(non_camel_case_types)]
mod darwin_fd_limit {
/*!
* darwin_fd_limit exists to work around an issue where launchctl on Mac OS X defaults the
* rlimit maxfiles to 256/unlimited. The default soft limit of 256 ends up being far too low
* for our multithreaded scheduler testing, depending on the number of cores available.
*
* This fixes issue #7772.
*/
use libc;
type rlim_t = libc::uint64_t;
#[repr(C)]

12
src/libstd/io/timer.rs
View file

@ -8,14 +8,10 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*!
Synchronous Timers
This module exposes the functionality to create timers, block the current task,
and create receivers which will receive notifications after a period of time.
*/
//! Synchronous Timers
//!
//! This module exposes the functionality to create timers, block the current task,
//! and create receivers which will receive notifications after a period of time.
// FIXME: These functions take Durations but only pass ms to the backend impls.

2
src/libstd/io/util.rs
View file

@ -8,7 +8,7 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
/*! Utility implementations of Reader and Writer */
//! Utility implementations of Reader and Writer
use prelude::*;
use cmp;