Add async support for Tokio runtime

.cargo/README.md

@@ -27,7 +27,7 @@ cargo add chksum-sha2-512
 
 ## Usage
 
-Use the `chksum` function to calcualate digest of file, directory and so on.
+Use the `chksum` function to calculate digest of file, directory and so on.
 
 ```rust
 use chksum_sha2_512 as sha2_512;

CHANGELOG.md

@@ -5,10 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Added async support for Tokio runtime.
+
 ## [0.0.0] - 2023-12-21
 
 ### Added
 
 - Initial release.
 
+[Unreleased]: https://github.com/chksum-rs/sha2-512/compare/v0.0.0...HEAD
 [0.0.0]: https://github.com/chksum-rs/sha2-512/releases/tag/v0.0.0

Cargo.toml

@@ -16,16 +16,21 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
-chksum-core = "0.0.0"
+chksum-core = "0.1.0"
 chksum-hash-sha2-512 = "0.0.0"
-chksum-reader = { version = "0.0.0", optional = true }
-chksum-writer = { version = "0.0.0", optional = true }
+chksum-reader = { version = "0.1.0", optional = true }
+chksum-writer = { version = "0.1.0", optional = true }
+tokio = { version = "1.37.0", features = ["io-util"], optional = true }
 
 [dev-dependencies]
 assert_fs = { version = "1.0.13", features = ["color-auto"] }
 thiserror = "1.0.51"
+tokio = { version = "1.37.0", features = ["macros", "rt", "rt-multi-thread"] }
 
 [features]
 default = []
 reader = ["chksum-reader"]
 writer = ["chksum-writer"]
+
+# async runtimes
+async-runtime-tokio = ["chksum-core/async-runtime-tokio", "chksum-reader?/async-runtime-tokio", "chksum-writer?/async-runtime-tokio", "tokio"]

README.md

@@ -27,7 +27,7 @@ cargo add chksum-sha2-512
 
 ## Usage
 
-Use the `chksum` function to calcualate digest of file, directory and so on.
+Use the `chksum` function to calculate digest of file, directory and so on.
 
 ```rust
 use chksum_sha2_512 as sha2_512;

src/lib.rs

@@ -19,7 +19,7 @@
 //!
 //! # Usage
 //!
-//! Use the [`chksum`] function to calcualate digest of file, directory and so on.
+//! Use the [`chksum`] function to calculate digest of file, directory and so on.
 //!
 //! ```rust
 //! # use std::path::Path;
@@ -39,6 +39,30 @@
 //! # }
 //! ```
 //!
+//! ## Asynchronous Runtime
+//!
+//! Use the [`async_chksum`] function to calculate digest of file, directory and so on.
+//!
+//! ```rust
+//! # #[cfg(feature = "async-runtime-tokio")]
+//! # {
+//! # use std::path::Path;
+//! # use chksum_sha2_512::Result;
+//! use chksum_sha2_512 as sha2_512;
+//! use tokio::fs::File;
+//!
+//! # async fn wrapper(path: &Path) -> Result<()> {
+//! let file = File::open(path).await?;
+//! let digest = sha2_512::async_chksum(file).await?;
+//! assert_eq!(
+//!     digest.to_hex_lowercase(),
+//!     "ed59c5759a9ece516cec0c0623142d0e9fe70a27d750eee7fd38f4550d50addd873d0fa1a51fc823c1e3d5cada203f4a05d8325caacb7d3e0727a701f3f07e5f"
+//! );
+//! # Ok(())
+//! # }
+//! # }
+//! ```
+//!
 //! # Input Types
 //!
 //! ## Bytes
@@ -231,6 +255,12 @@
 //! cargo add chksum-sha2-512 --features reader,writer
 //! ```
 //!
+//! ## Asynchronous Runtime
+//!
+//! * `async-runtime-tokio`: Enables async interface for Tokio runtime.
+//!
+//! By default, neither of these features is enabled.
+//!
 //! # License
 //!
 //! This crate is licensed under the MIT License.
@@ -246,14 +276,23 @@ pub mod writer;
 use std::fmt::{self, Display, Formatter, LowerHex, UpperHex};
 
 use chksum_core as core;
+#[cfg(feature = "async-runtime-tokio")]
+#[doc(no_inline)]
+pub use chksum_core::AsyncChksumable;
 #[doc(no_inline)]
 pub use chksum_core::{Chksumable, Error, Hash, Hashable, Result};
 #[doc(no_inline)]
 pub use chksum_hash_sha2_512 as hash;
 
+#[cfg(all(feature = "reader", feature = "async-runtime-tokio"))]
+#[doc(inline)]
+pub use crate::reader::AsyncReader;
 #[cfg(feature = "reader")]
 #[doc(inline)]
 pub use crate::reader::Reader;
+#[cfg(all(feature = "writer", feature = "async-runtime-tokio"))]
+#[doc(inline)]
+pub use crate::writer::AsyncWriter;
 #[cfg(feature = "writer")]
 #[doc(inline)]
 pub use crate::writer::Writer;
@@ -335,6 +374,28 @@ pub fn chksum(data: impl core::Chksumable) -> Result<Digest> {
     core::chksum::<SHA2_512>(data)
 }
 
+/// Computes the hash of the given input.
+///
+/// # Example
+///
+/// ```rust
+/// use chksum_sha2_512 as sha2_512;
+///
+/// # async fn wrapper() {
+/// let data = b"example data";
+/// if let Ok(digest) = sha2_512::async_chksum(data).await {
+///     assert_eq!(
+///         digest.to_hex_lowercase(),
+///         "ed59c5759a9ece516cec0c0623142d0e9fe70a27d750eee7fd38f4550d50addd873d0fa1a51fc823c1e3d5cada203f4a05d8325caacb7d3e0727a701f3f07e5f"
+///     );
+/// }
+/// # }
+/// ```
+#[cfg(feature = "async-runtime-tokio")]
+pub async fn async_chksum(data: impl core::AsyncChksumable) -> Result<Digest> {
+    core::async_chksum::<SHA2_512>(data).await
+}
+
 /// The SHA-2 512 hash instance.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
 pub struct SHA2_512 {

src/reader.rs

@@ -47,24 +47,36 @@
 use std::io::Read;
 
 use chksum_reader as reader;
+#[cfg(feature = "async-runtime-tokio")]
+use tokio::io::AsyncRead;
 
 use crate::SHA2_512;
 
 /// A specialized [`Reader`](reader::Reader) type with the [`SHA2_512`] hash algorithm.
 pub type Reader<R> = reader::Reader<R, SHA2_512>;
 
+#[cfg(feature = "async-runtime-tokio")]
+/// A specialized [`AsyncReader`](reader::AsyncReader) type with the [`SHA2_512`] hash algorithm.
+pub type AsyncReader<R> = reader::AsyncReader<R, SHA2_512>;
+
 /// Creates new [`Reader`].
-pub fn new<R>(inner: R) -> Reader<R>
-where
-    R: Read,
-{
+pub fn new(inner: impl Read) -> Reader<impl Read> {
     reader::new(inner)
 }
 
 /// Creates new [`Reader`] with provided hash.
-pub fn with_hash<R>(inner: R, hash: SHA2_512) -> Reader<R>
-where
-    R: Read,
-{
+pub fn with_hash(inner: impl Read, hash: SHA2_512) -> Reader<impl Read> {
     reader::with_hash(inner, hash)
 }
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncReader`].
+pub fn async_new(inner: impl AsyncRead) -> AsyncReader<impl AsyncRead> {
+    reader::async_new(inner)
+}
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncReader`] with provided hash.
+pub fn async_with_hash(inner: impl AsyncRead, hash: SHA2_512) -> AsyncReader<impl AsyncRead> {
+    reader::async_with_hash(inner, hash)
+}

src/writer.rs

@@ -45,12 +45,18 @@
 use std::io::Write;
 
 use chksum_writer as writer;
+#[cfg(feature = "async-runtime-tokio")]
+use tokio::io::AsyncWrite;
 
 use crate::SHA2_512;
 
 /// A specialized [`Writer`](writer::Writer) type with the [`SHA2_512`] hash algorithm.
 pub type Writer<W> = writer::Writer<W, SHA2_512>;
 
+#[cfg(feature = "async-runtime-tokio")]
+/// A specialized [`AsyncWriter`](writer::AsyncWriter) type with the [`SHA2_512`] hash algorithm.
+pub type AsyncWriter<R> = writer::AsyncWriter<R, SHA2_512>;
+
 /// Creates new [`Writer`].
 pub fn new(inner: impl Write) -> Writer<impl Write> {
     writer::new(inner)
@@ -60,3 +66,15 @@ pub fn new(inner: impl Write) -> Writer<impl Write> {
 pub fn with_hash(inner: impl Write, hash: SHA2_512) -> Writer<impl Write> {
     writer::with_hash(inner, hash)
 }
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncWriter`].
+pub fn async_new(inner: impl AsyncWrite) -> AsyncWriter<impl AsyncWrite> {
+    writer::async_new(inner)
+}
+
+#[cfg(feature = "async-runtime-tokio")]
+/// Creates new [`AsyncWriter`] with provided hash.
+pub fn async_with_hash(inner: impl AsyncWrite, hash: SHA2_512) -> AsyncWriter<impl AsyncWrite> {
+    writer::async_with_hash(inner, hash)
+}