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    feature = "deflate64",
141    doc = "`deflate64` | (encoder not implemented), [`Deflate64Decoder`](?search=Deflate64Decoder)"
142)]
143#![cfg_attr(
144    not(feature = "deflate64"),
145    doc = "`deflate64` (*inactive*) | (encoder not implemented), `Deflate64Decoder`"
146)]
147//!
148
149//! ## Unstable features
150//!
151//! Some features are not yet covered by this crate's stability guarantees. They only take effect
152//! when the crate is also built with `--cfg async_compression_unstable`, for example through
153//! `RUSTFLAGS="--cfg async_compression_unstable"`, and they may change or be removed in any
154//! release:
155//!
156//! - `brotli-mbrotli` adds `MbrotliEncoder` and `MbrotliDecoder`, a Brotli implementation backed by
157//!   the pure-Rust [`mbrotli`](https://docs.rs/mbrotli) crate. It is an alternative to the `brotli`
158//!   feature and produces the same format. `mbrotli` requires Rust 1.89 or newer.
159//!
160
161//! ## Multi-thread support
162//! The `xz` compression algorithm supports multi-threaded compression and decompression.
163//! Enable the `xz-parallel` feature to enable multi-threading support.
164//!
165
166#![cfg_attr(docsrs, feature(doc_cfg))]
167#![cfg_attr(not(all), allow(unused))]
168
169#[macro_use]
170mod macros;
171
172/// Generic, async runtime agonistc implementation of en/decoders
173mod generic;
174
175#[cfg(feature = "futures-io")]
176pub mod futures;
177#[cfg(feature = "tokio")]
178pub mod tokio;
179
180pub use compression_codecs as codecs;
181pub use compression_core as core;
182
183pub use core::Level;
184
185#[cfg(feature = "zstd")]
186pub use codecs::zstd::params as zstd;
187
188#[cfg(feature = "lz4")]
189pub use codecs::lz4::params as lz4;
190
191#[cfg(feature = "brotli")]
192pub use codecs::brotli::params as brotli;
193
194#[cfg(all(feature = "brotli-mbrotli", async_compression_unstable))]
195pub use codecs::mbrotli::params as mbrotli;
async_compression/lib.rs

async_compression/
lib.rs
