async_compression/
lib.rs

1//! Adaptors between compression crates and Rust's modern asynchronous IO types.
2//!
3
4//! # Feature Organization
5//!
6//! This crate is divided up along two axes, which can each be individually selected via Cargo
7//! features.
8//!
9//! All features are disabled by default, you should enable just the ones you need from the lists
10//! below.
11//!
12//! If you want to pull in everything there are three group features defined:
13//!
14
15//!  Feature | Does
16//! ---------|------
17//!  `all`   | Activates all implementations and algorithms.
18//!  `all-implementations` | Activates all implementations, needs to be paired with a selection of algorithms
19//!  `all-algorithms` | Activates all algorithms, needs to be paired with a selection of implementations
20//!
21
22//! ## IO implementation
23//!
24//! The first division is which underlying asynchronous IO trait will be wrapped, these are
25//! available as separate features that have corresponding top-level modules:
26//!
27
28//!  Feature | Type
29//! ---------|------
30// TODO: Kill rustfmt on this section, `#![rustfmt::skip::attributes(cfg_attr)]` should do it, but
31// that's unstable
32#![allow(unexpected_cfgs)]
33#![cfg_attr(
34    feature = "futures-io",
35    doc = "[`futures-io`](futures_io) | [`futures::io::AsyncBufRead`](futures_io::AsyncBufRead), [`futures::io::AsyncWrite`](futures_io::AsyncWrite)"
36)]
37#![cfg_attr(
38    not(feature = "futures-io"),
39    doc = "`futures-io` (*inactive*) | `futures::io::AsyncBufRead`, `futures::io::AsyncWrite`"
40)]
41#![cfg_attr(
42    feature = "tokio",
43    doc = "[`tokio`] | [`tokio::io::AsyncBufRead`](::tokio::io::AsyncBufRead), [`tokio::io::AsyncWrite`](::tokio::io::AsyncWrite)"
44)]
45#![cfg_attr(
46    not(feature = "tokio"),
47    doc = "`tokio` (*inactive*) | `tokio::io::AsyncBufRead`, `tokio::io::AsyncWrite`"
48)]
49//!
50
51//! ## Compression algorithm
52//!
53//! The second division is which compression schemes to support, there are currently a few
54//! available choices, these determine which types will be available inside the above modules:
55//!
56
57//!  Feature | Types
58//! ---------|------
59#![cfg_attr(
60    feature = "brotli",
61    doc = "`brotli` | [`BrotliEncoder`](?search=BrotliEncoder), [`BrotliDecoder`](?search=BrotliDecoder)"
62)]
63#![cfg_attr(
64    not(feature = "brotli"),
65    doc = "`brotli` (*inactive*) | `BrotliEncoder`, `BrotliDecoder`"
66)]
67#![cfg_attr(
68    all(feature = "brotli-mbrotli", async_compression_unstable),
69    doc = "`brotli-mbrotli` (*unstable*) | [`MbrotliEncoder`](?search=MbrotliEncoder), [`MbrotliDecoder`](?search=MbrotliDecoder)"
70)]
71#![cfg_attr(
72    not(all(feature = "brotli-mbrotli", async_compression_unstable)),
73    doc = "`brotli-mbrotli` (*unstable*, *inactive*) | `MbrotliEncoder`, `MbrotliDecoder`"
74)]
75#![cfg_attr(
76    feature = "bzip2",
77    doc = "`bzip2` | [`BzEncoder`](?search=BzEncoder), [`BzDecoder`](?search=BzDecoder)"
78)]
79#![cfg_attr(
80    not(feature = "bzip2"),
81    doc = "`bzip2` (*inactive*) | `BzEncoder`, `BzDecoder`"
82)]
83#![cfg_attr(
84    feature = "deflate",
85    doc = "`deflate` | [`DeflateEncoder`](?search=DeflateEncoder), [`DeflateDecoder`](?search=DeflateDecoder)"
86)]
87#![cfg_attr(
88    not(feature = "deflate"),
89    doc = "`deflate` (*inactive*) | `DeflateEncoder`, `DeflateDecoder`"
90)]
91#![cfg_attr(
92    feature = "gzip",
93    doc = "`gzip` | [`GzipEncoder`](?search=GzipEncoder), [`GzipDecoder`](?search=GzipDecoder)"
94)]
95#![cfg_attr(
96    not(feature = "gzip"),
97    doc = "`gzip` (*inactive*) | `GzipEncoder`, `GzipDecoder`"
98)]
99#![cfg_attr(
100    feature = "lz4",
101    doc = "`lz4` | [`Lz4Encoder`](?search=Lz4Encoder), [`Lz4Decoder`](?search=Lz4Decoder)"
102)]
103#![cfg_attr(
104    not(feature = "lz4"),
105    doc = "`lz4` (*inactive*) | `Lz4Encoder`, `Lz4Decoder`"
106)]
107#![cfg_attr(
108    feature = "lzma",
109    doc = "`lzma` | [`LzmaEncoder`](?search=LzmaEncoder), [`LzmaDecoder`](?search=LzmaDecoder)"
110)]
111#![cfg_attr(
112    not(feature = "lzma"),
113    doc = "`lzma` (*inactive*) | `LzmaEncoder`, `LzmaDecoder`"
114)]
115#![cfg_attr(
116    feature = "xz",
117    doc = "`xz` | [`XzEncoder`](?search=XzEncoder), [`XzDecoder`](?search=XzDecoder)"
118)]
119#![cfg_attr(
120    not(feature = "xz"),
121    doc = "`xz` (*inactive*) | `XzEncoder`, `XzDecoder`"
122)]
123#![cfg_attr(
124    feature = "zlib",
125    doc = "`zlib` | [`ZlibEncoder`](?search=ZlibEncoder), [`ZlibDecoder`](?search=ZlibDecoder)"
126)]
127#![cfg_attr(
128    not(feature = "zlib"),
129    doc = "`zlib` (*inactive*) | `ZlibEncoder`, `ZlibDecoder`"
130)]
131#![cfg_attr(
132    feature = "zstd",
133    doc = "`zstd` | [`ZstdEncoder`](?search=ZstdEncoder), [`ZstdDecoder`](?search=ZstdDecoder)"
134)]
135#![cfg_attr(
136    not(feature = "zstd"),
137    doc = "`zstd` (*inactive*) | `ZstdEncoder`, `ZstdDecoder`"
138)]
139#![cfg_attr(
140    all(feature = "zstd-mzstd", async_compression_unstable),
141    doc = "`zstd-mzstd` (*unstable*) | [`MzstdEncoder`](?search=MzstdEncoder), [`MzstdDecoder`](?search=MzstdDecoder)"
142)]
143#![cfg_attr(
144    not(all(feature = "zstd-mzstd", async_compression_unstable)),
145    doc = "`zstd-mzstd` (*unstable*, *inactive*) | `MzstdEncoder`, `MzstdDecoder`"
146)]
147#![cfg_attr(
148    feature = "deflate64",
149    doc = "`deflate64` | (encoder not implemented), [`Deflate64Decoder`](?search=Deflate64Decoder)"
150)]
151#![cfg_attr(
152    not(feature = "deflate64"),
153    doc = "`deflate64` (*inactive*) | (encoder not implemented), `Deflate64Decoder`"
154)]
155//!
156
157//! ## Unstable features
158//!
159//! Some features are not yet covered by this crate's stability guarantees. They only take effect
160//! when the crate is also built with `--cfg async_compression_unstable`, for example through
161//! `RUSTFLAGS="--cfg async_compression_unstable"`, and they may change or be removed in any
162//! release:
163//!
164//! - `brotli-mbrotli` adds `MbrotliEncoder` and `MbrotliDecoder`, a Brotli implementation backed by
165//!   the pure-Rust [`mbrotli`](https://docs.rs/mbrotli) crate. It is an alternative to the `brotli`
166//!   feature and produces the same format. `mbrotli` requires Rust 1.89 or newer.
167//! - `zstd-mzstd` adds `MzstdEncoder` and `MzstdDecoder`, a Zstandard implementation backed by the
168//!   pure-Rust [`mzstd`](https://docs.rs/mzstd) crate. It is an alternative to the `zstd` feature
169//!   and produces the same format. `mzstd` requires Rust 1.89 or newer.
170//!
171
172//! ## Multi-thread support
173//! The `xz` compression algorithm supports multi-threaded compression and decompression.
174//! Enable the `xz-parallel` feature to enable multi-threading support.
175//!
176
177#![cfg_attr(docsrs, feature(doc_cfg))]
178#![cfg_attr(not(all), allow(unused))]
179
180#[macro_use]
181mod macros;
182
183/// Generic, async runtime agonistc implementation of en/decoders
184mod generic;
185
186#[cfg(feature = "futures-io")]
187pub mod futures;
188#[cfg(feature = "tokio")]
189pub mod tokio;
190
191pub use compression_codecs as codecs;
192pub use compression_core as core;
193
194pub use core::Level;
195
196#[cfg(feature = "zstd")]
197pub use codecs::zstd::params as zstd;
198
199#[cfg(feature = "lz4")]
200pub use codecs::lz4::params as lz4;
201
202#[cfg(feature = "brotli")]
203pub use codecs::brotli::params as brotli;
204
205#[cfg(all(feature = "brotli-mbrotli", async_compression_unstable))]
206pub use codecs::mbrotli::params as mbrotli;
207
208#[cfg(all(feature = "zstd-mzstd", async_compression_unstable))]
209pub use codecs::mzstd::params as mzstd;
async_compression/lib.rs

async_compression/
lib.rs
