itsscb/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2025-09-28 12:10:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

fs: added usage examples/doctests to File (#786)

Browse Source
This commit is contained in:
Matt Gathu 2018-12-02 03:07:48 +01:00 committed by Toby Lawrence
parent 8263e5f18d
commit 2283b63e9e
1 changed files with 281 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

282
tokio-fs/src/file/mod.rs
View File

@ -34,6 +34,46 @@ use std::path::Path;
/// Files are automatically closed when they go out of scope.
///
/// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
///
/// # Examples
///
/// Create a new file and asynchronously write bytes to it:
///
/// ```no_run
/// extern crate tokio;
///
/// use tokio::prelude::{AsyncWrite, Future};
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|mut file| file.poll_write(b"hello, world!"))
/// .map(|res| {
/// println!("{:?}", res);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
///
/// Read the contents of a file into a buffer
///
/// ```no_run
/// extern crate tokio;
///
/// use tokio::prelude::{AsyncRead, Future};
///
/// fn main() {
/// let task = tokio::fs::File::open("foo.txt")
/// .and_then(|mut file| {
/// let mut contents = vec![];
/// file.read_buf(&mut contents)
/// .map(|res| {
/// println!("{:?}", res);
/// })
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
/// tokio::run(task);
/// }
/// ```
#[derive(Debug)]
pub struct File {
std: Option<StdFile>,
@ -52,6 +92,23 @@ impl File {
/// runtime or if the underlying [`open`] call results in an error.
///
/// [`open`]: https://doc.rust-lang.org/std/fs/struct.File.html#method.open
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
/// fn main() {
/// let task = tokio::fs::File::open("foo.txt").and_then(|file| {
/// // do something with the file ...
/// file.metadata().map(|md| println!("{:?}", md))
/// }).map_err(|e| {
/// // handle errors
/// eprintln!("IO error: {:?}", e);
/// });
/// tokio::run(task);
/// }
/// ```
pub fn open<P>(path: P) -> OpenFuture<P>
where P: AsRef<Path> + Send + 'static,
{
@ -73,15 +130,45 @@ impl File {
/// runtime or if the underlying [`create`] call results in an error.
///
/// [`create`]: https://doc.rust-lang.org/std/fs/struct.File.html#method.create
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|file| {
/// // do something with the created file ...
/// file.metadata().map(|md| println!("{:?}", md))
/// }).map_err(|e| {
/// // handle errors
/// eprintln!("IO error: {:?}", e);
/// });
/// tokio::run(task);
/// }
/// ```
pub fn create<P>(path: P) -> CreateFuture<P>
where P: AsRef<Path> + Send + 'static,
{
CreateFuture::new(path)
}
/// Convert a [`std::fs::File`][std] to a `tokio_fs::File`.
/// Convert a [`std::fs::File`][std] to a [`tokio_fs::File`][file].
///
/// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
/// [file]: struct.File.html
///
/// Examples
/// ```no_run
/// # extern crate tokio;
/// use std::fs::File;
///
/// fn main() {
/// let std_file = File::open("foo.txt").unwrap();
/// let file = tokio::fs::File::from_std(std_file);
/// }
/// ```
pub fn from_std(std: StdFile) -> File {
File { std: Some(std) }
}
@ -98,6 +185,25 @@ impl File {
/// # Errors
///
/// Seeking to a negative offset is considered an error.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
/// use std::io::SeekFrom;
///
/// fn main() {
/// let task = tokio::fs::File::open("foo.txt")
/// // move cursor 6 bytes from the start of the file
/// .and_then(|mut file| file.poll_seek(SeekFrom::Start(6)))
/// .map(|res| {
/// println!("{:?}", res);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_seek(&mut self, pos: io::SeekFrom) -> Poll<u64, io::Error> {
::blocking_io(|| self.std().seek(pos))
}
@ -108,6 +214,25 @@ impl File {
///
/// This method consumes the `File` and returns it back when the future
/// completes.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
/// use std::io::SeekFrom;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|file| file.seek(SeekFrom::Start(6)))
/// .map(|file| {
/// // handle returned file ..
/// # println!("{:?}", file);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn seek(self, pos: io::SeekFrom) -> SeekFuture {
SeekFuture::new(self, pos)
}
@ -116,6 +241,27 @@ impl File {
///
/// This function will attempt to ensure that all in-core data reaches the
/// filesystem before returning.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::{AsyncWrite, Future};
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|mut file| {
/// file.poll_write(b"hello, world!")?;
/// file.poll_sync_all()
/// })
/// .map(|res| {
/// // handle returned result ..
/// # println!("{:?}", res);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_sync_all(&mut self) -> Poll<(), io::Error> {
::blocking_io(|| self.std().sync_all())
}
@ -128,6 +274,27 @@ impl File {
/// operations.
///
/// Note that some platforms may simply implement this in terms of `poll_sync_all`.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::{AsyncWrite, Future};
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|mut file| {
/// file.poll_write(b"hello, world!")?;
/// file.poll_sync_data()
/// })
/// .map(|res| {
/// // handle returned result ..
/// # println!("{:?}", res);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_sync_data(&mut self) -> Poll<(), io::Error> {
::blocking_io(|| self.std().sync_data())
}
@ -143,16 +310,71 @@ impl File {
///
/// This function will return an error if the file is not opened for
/// writing.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|mut file| {
/// file.poll_set_len(10)
/// })
/// .map(|res| {
/// // handle returned result ..
/// # println!("{:?}", res);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_set_len(&mut self, size: u64) -> Poll<(), io::Error> {
::blocking_io(|| self.std().set_len(size))
}
/// Queries metadata about the underlying file.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|file| file.metadata())
/// .map(|metadata| {
/// println!("{:?}", metadata);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn metadata(self) -> MetadataFuture {
MetadataFuture::new(self)
}
/// Queries metadata about the underlying file.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|mut file| file.poll_metadata())
/// .map(|metadata| {
/// // metadata is of type Async::Ready<Metadata>
/// println!("{:?}", metadata);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_metadata(&mut self) -> Poll<Metadata, io::Error> {
::blocking_io(|| self.std().metadata())
}
@ -160,6 +382,24 @@ impl File {
/// Create a new `File` instance that shares the same underlying file handle
/// as the existing `File` instance. Reads, writes, and seeks will affect both
/// File instances simultaneously.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|mut file| file.poll_try_clone())
/// .map(|clone| {
/// // do something with the clone
/// # println!("{:?}", clone);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_try_clone(&mut self) -> Poll<File, io::Error> {
::blocking_io(|| {
let std = self.std().try_clone()?;
@ -182,6 +422,28 @@ impl File {
/// This function will return an error if the user lacks permission change
/// attributes on the underlying file. It may also return an error in other
/// os-specific unspecified cases.
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .and_then(|file| file.metadata())
/// .map(|(mut file, metadata)| {
/// let mut perms = metadata.permissions();
/// perms.set_readonly(true);
/// match file.poll_set_permissions(perms) {
/// Err(e) => eprintln!("{}", e),
/// _ => println!("permissions set!"),
/// }
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn poll_set_permissions(&mut self, perm: Permissions) -> Poll<(), io::Error> {
::blocking_io(|| self.std().set_permissions(perm))
}
@ -193,6 +455,24 @@ impl File {
/// This function will panic if `shutdown` has been called.
///
/// [std]: https://doc.rust-lang.org/std/fs/struct.File.html
///
/// # Examples
///
/// ```no_run
/// # extern crate tokio;
/// use tokio::prelude::Future;
///
/// fn main() {
/// let task = tokio::fs::File::create("foo.txt")
/// .map(|file| {
/// let std_file = file.into_std();
/// // do something with the std::fs::File
/// # println!("{:?}", std_file);
/// }).map_err(|err| eprintln!("IO error: {:?}", err));
///
/// tokio::run(task);
/// }
/// ```
pub fn into_std(mut self) -> StdFile {
self.std.take().expect("`File` instance already shutdown")
}